home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / developer-tools / guis / gadutil / docs / gadutil.doc < prev    next >
Text File  |  1996-07-16  |  90KB  |  2,686 lines
  1. TABLE OF CONTENTS
  2.  
  3. gadutil.library/GU_AddTail
  4. gadutil.library/GU_AttachList
  5. gadutil.library/GU_BeginRefresh
  6. gadutil.library/GU_BlockInput
  7. gadutil.library/GU_ChangeStr
  8. gadutil.library/GU_CheckVersion
  9. gadutil.library/GU_ClearList
  10. gadutil.library/GU_ClearWindow
  11. gadutil.library/GU_CloseCatalog
  12. gadutil.library/GU_CloseFont
  13. gadutil.library/GU_CoordsInGadBox
  14. gadutil.library/GU_CountNodes
  15. gadutil.library/GU_CreateContext
  16. gadutil.library/GU_CreateGadgetA
  17. gadutil.library/GU_CreateLocMenuA
  18. gadutil.library/GU_CreateMenusA
  19. gadutil.library/GU_DetachList
  20. gadutil.library/GU_DisableGadget
  21. gadutil.library/GU_DrawBevelBoxA
  22. gadutil.library/GU_EndRefresh
  23. gadutil.library/GU_FilterIMsg
  24. gadutil.library/GU_FindNode
  25. gadutil.library/GU_FreeGadgets
  26. gadutil.library/GU_FreeInput
  27. gadutil.library/GU_FreeLayoutGadgets
  28. gadutil.library/GU_FreeMenus
  29. gadutil.library/GU_FreeVisualInfo
  30. gadutil.library/GU_GadgetArrayIndex
  31. gadutil.library/GU_GetGadgetAttrsA
  32. gadutil.library/GU_GetGadgetPtr
  33. gadutil.library/GU_GetIMsg
  34. gadutil.library/GU_GetLocaleStr
  35. gadutil.library/GU_GetVisualInfoA
  36. gadutil.library/GU_LayoutGadgetsA
  37. gadutil.library/GU_LayoutMenuItemsA
  38. gadutil.library/GU_LayoutMenusA
  39. gadutil.library/GU_NewList
  40. gadutil.library/GU_NodeDown
  41. gadutil.library/GU_NodeUp
  42. gadutil.library/GU_OpenCatalog
  43. gadutil.library/GU_OpenFont
  44. gadutil.library/GU_PostFilterIMsg
  45. gadutil.library/GU_RefreshBoxes
  46. gadutil.library/GU_RefreshWindow
  47. gadutil.library/GU_ReplyIMsg
  48. gadutil.library/GU_SetGadgetAttrsA
  49. gadutil.library/GU_SetGUGadAttrsA
  50. gadutil.library/GU_SetToggle
  51. gadutil.library/GU_SizeWindow
  52. gadutil.library/GU_SortList
  53. gadutil.library/GU_TextWidth
  54. gadutil.library/GU_UpdateProgress
  55. Œ gadutil.library/GU_AddTail                         gadutil.library/GU_AddTail
  56.  
  57.    NAME
  58.     GU_AddTail -- Add a node to the end of a listview's list.
  59.  
  60.    SYNOPSIS
  61.     node = GU_AddTail(gad, string, list)
  62.     D0, SR (Z)        D0   A0      A1
  63.  
  64.     struct Node *GU_AddTail(struct Gadget *, STRPTR, struct List *);
  65.  
  66.    FUNCTION
  67.     Add a node to the end of a list linked to a gadget (eg. a ListView).
  68.  
  69.     Normally this is used to add a node to a listview list, but it can
  70.     also be used if you eg have another list that that contains
  71.     information about the items in the listview. This list will then
  72.     also be deallocated at the same time as the listview's own list.
  73.     If you do this, be sure to clear the list header of this other list
  74.     when you want to deallocate the list (you can use the GU_NewList
  75.     function).
  76.  
  77.    INPUTS
  78.     gad    - Gadget to keep the nodes in (ie the ListView gadget).
  79.  
  80.     string - String to put in the nodes' LN_NAME field (visible entry).
  81.  
  82.     list   - List to add the node to.
  83.  
  84.    RESULT
  85.     node - Struct Node for success, FALSE for error.
  86.     SR(Z)- 0 for success, 1 for error.
  87.  
  88.    NOTES
  89.     The SR(Z) is probably most usable for assembly programmers.
  90.  
  91.    BUGS
  92.     none known
  93.  
  94.    SEE ALSO
  95.     GU_CountNodes(), GU_NewList(), GU_ClearList(), GU_DetachList(),
  96.     GU_AttachList(), GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_SortList()
  97. gadutil.library/GU_AttachList                   gadutil.library/GU_AttachList
  98.  
  99.    NAME
  100.     GU_AttachList -- Change a listview's current list.
  101.  
  102.    SYNOPSIS
  103.     GU_AttachList(gad, win, list)
  104.                   D0   A0   A1
  105.  
  106.     VOID GU_AttachList(struct Gadget *, struct Window *, struct List *);
  107.  
  108.    FUNCTION
  109.     Attach a new (or changed) list to a listview. The new list will be
  110.     shown immediately.
  111.  
  112.    INPUTS
  113.     gad  - Gadget to change.
  114.     win  - Window that the gadget is located in.
  115.     list - List to connect to the listview gadget.
  116.  
  117.    RESULT
  118.     none
  119.  
  120.    BUGS
  121.     none known
  122.  
  123.    SEE ALSO
  124.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_NewList()
  125.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  126. gadutil.library/GU_BeginRefresh               gadutil.library/GU_BeginRefresh
  127.  
  128.    NAME
  129.     GU_BeginRefresh -- Begin refreshing friendly to GadTools.
  130.  
  131.    SYNOPSIS
  132.     GU_BeginRefresh(win)
  133.                     A0
  134.  
  135.     VOID GU_BeginRefresh(struct Window *);
  136.  
  137.    FUNCTION
  138.  
  139.     Invokes the intuition.library/BeginRefresh() function in a manner
  140.     friendly to the Gadget Toolkit. This function call permits the
  141.     GadTools gadgets to refresh themselves at the correct time.
  142.     Call GU_EndRefresh() function when done.
  143.  
  144.    INPUTS
  145.     win - pointer to Window structure for which a IDCMP_REFRESHWINDOW
  146.           IDCMP event was received.
  147.  
  148.    NOTES
  149.     See gadtools/GT_BeginRefresh() for more information.
  150.  
  151.    SEE ALSO
  152.     GU_EndRefresh(), gadtools/GT_BeginRefresh(), intuition/BeginRefresh()
  153. gadutil.library/GU_BlockInput                   gadutil.library/GU_BlockInput
  154.  
  155.    NAME
  156.     GU_BlockInput -- Block all input to a window.
  157.  
  158.    SYNOPSIS
  159.     GU_BlockInput(window)
  160.                   A0
  161.  
  162.     VOID GU_BlockInput(struct Window *);
  163.  
  164.    FUNCTION
  165.     Changes the window's pointer to the standard wait pointer (OS 2.0)
  166.     or the preferred wait pointer (OS 3.0+) and opens a requester to
  167.     block the user input of the given window. The requester that is
  168.     opened is not visible.
  169.  
  170.    INPUTS
  171.     window - the parent window for the requester. This is the window
  172.          that will be blocked for user input.
  173.  
  174.    EXAMPLE
  175.  
  176.     BlockInput(myWin);
  177.     About();
  178.     FreeInput();
  179.  
  180.     Will block the parent window for user input while displaying the
  181.     About requester of a program.
  182.  
  183.    SEE ALSO
  184.     GU_FreeInput()
  185. gadutil.library/GU_ChangeStr                     gadutil.library/GU_ChangeStr
  186.  
  187.    NAME
  188.     GU_ChangeStr -- Change the contents of string gadget.
  189.  
  190.    SYNOPSIS
  191.     GU_ChangeStr(gad, string, win)
  192.                  D0   A0      A1
  193.  
  194.     VOID GU_ChangeStr(struct Gadget *, STRPTR, struct Window *);
  195.  
  196.    FUNCTION
  197.     Change the string in a string gadget.
  198.  
  199.    INPUTS
  200.     gad    - Gadget to change
  201.     string - New string
  202.     win    - Window that the gadget is located in.
  203.  
  204.    RESULT
  205.     none
  206.  
  207.    BUGS
  208.     none known
  209.  
  210.    SEE ALSO
  211. gadutil.library/GU_CheckVersion               gadutil.library/GU_CheckVersion
  212.  
  213.    NAME
  214.     GU_CheckVersion -- Check the version.revision of a library
  215.  
  216.    SYNOPSIS
  217.     success = GU_CheckVersion(library, version, revision)
  218.     D0, SR(Z)                 A0       D0       D1
  219.  
  220.     BOOL GU_CheckVersion(struct Library *, UWORD, UWORD);
  221.  
  222.    FUNCTION
  223.     Compares a library's version and revision with a required one.
  224.     
  225.    INPUTS
  226.     library  - a pointer to an opened library/device
  227.     version  - the version of the library that is required
  228.     revision - the revision of the library that is required
  229.  
  230.    RESULT
  231.     success - TRUE if the required version is older or equal to the
  232.           opened one. FALSE otherwise.
  233.     SR(Z)   - 0 if function returns TRUE, 1 otherwise
  234.  
  235.    BUGS
  236.     none known
  237.  
  238.    SEE ALSO
  239. gadutil.library/GU_ClearList                     gadutil.library/GU_ClearList
  240.  
  241.    NAME
  242.     GU_ClearList -- Clear a listview gadget and deallocate all its nodes.
  243.  
  244.    SYNOPSIS
  245.     GU_ClearList(gad, win, list)
  246.                  D0   A0   A1
  247.  
  248.     VOID GU_ClearList(struct Gadget *, struct Window *, struct List *);
  249.  
  250.    FUNCTION
  251.     Clear a listview gadget and deallocate all nodes.
  252.  
  253.    INPUTS
  254.     gad  - Gadget To Change
  255.     win  - Window that the gadget is located in.
  256.     list - List structure to deallocate nodes from.
  257.  
  258.    RESULT
  259.     none
  260.  
  261.    BUGS
  262.     none known
  263.  
  264.    SEE ALSO
  265.     GU_AddTail(), GU_NewList(), GU_DetachList(), GU_AttachList()
  266.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  267. gadutil.library/GU_ClearWindow                 gadutil.library/GU_ClearWindow
  268.  
  269.    NAME
  270.     GU_ClearWindow -- Fill the inside of a window with selected color.
  271.  
  272.    SYNOPSIS
  273.     GU_ClearWindow(window, color)
  274.                    A0      D0
  275.  
  276.     VOID GU_ClearWindow(struct Window *, UWORD);
  277.  
  278.    FUNCTION
  279.     Fills the inner area of a window with given color.
  280.  
  281.    INPUTS
  282.     window - pointer to the window to be filled
  283.  
  284.     color - the color to use. Use color 0 to clear the window.
  285.  
  286.    BUGS
  287.     none known
  288.  
  289.    SEE ALSO
  290. gadutil.library/GU_CloseCatalog               gadutil.library/GU_CloseCatalog
  291.  
  292.    NAME
  293.     GU_CloseCatalog -- Close a message catalog.
  294.  
  295.    SYNOPSIS
  296.     GU_CloseCatalog(catalog)
  297.                     A0
  298.  
  299.     VOID GU_CloseCatalog(struct Catalog *);
  300.  
  301.    FUNCTION
  302.     Concludes access to a message catalog. The usage count of the
  303.     catalog is decremented. When this count reaches 0, the catalog
  304.     can be expunged from system memory whenever a memory panic occurs.
  305.  
  306.    INPUTS
  307.     catalog - the message catalog to close. A NULL catalog is a valid
  308.           parameter and is simply ignored.
  309.  
  310.    NOTES
  311.     This function is a shortcut to the locale/CloseCatalog() function.
  312.  
  313.    SEE ALSO
  314.     GU_OpenCatalog(), GU_GetLocaleStr()
  315. gadutil.library/GU_CloseFont                     gadutil.library/GU_CloseFont
  316.  
  317.    NAME
  318.     GU_CloseFont -- Release a pointer to a system font.
  319.  
  320.    SYNOPSIS
  321.     GU_CloseFont(font)
  322.                  A0
  323.  
  324.     VOID GU_CloseFont(struct TextFont *);
  325.  
  326.    FUNCTION
  327.     This function indicates that the font specified is no longer
  328.     in use. It is used to close a font opened by GU_OpenFont, so
  329.     that fonts that are no longer in use do not consume system
  330.     resources.
  331.  
  332.    INPUTS
  333.     font - a font pointer as returned by GU_OpenFont()
  334.  
  335.    RESULT
  336.  
  337.    BUGS
  338.     none known
  339.  
  340.    SEE ALSO
  341.     GU_OpenFont()
  342. gadutil.library/GU_CoordsInGadBox           gadutil.library/GU_CoordsInGadBox
  343.  
  344.    NAME
  345.     GU_CoordsInGadBox -- Check if a coordinate pair is within a gadget.
  346.  
  347.    SYNOPSIS
  348.     IsInBox = GU_CoordsInGadBox(coords, gad)
  349.     D0,SR(Z)                    D0      A0
  350.  
  351.     BOOL GU_CoordsInGadBox(ULONG, struct Gadget *);
  352.  
  353.    FUNCTION
  354.     Check if a coordinate pair is within a gadget's border. This
  355.     function may be used to make coordinate sensitive AppWindows
  356.     (allows the user to drop a file on a string gadget etc.).
  357.     To use this function, you must save the coordinates from the
  358.     recieved message (AppMessage, IntuiMessage) to have something
  359.     to compare against.
  360.  
  361.    INPUTS
  362.     coords - a combined LONG of both the X and Y coordinates to
  363.          compare against. The X coordinate should be in the
  364.          upper word of the parameter.
  365.  
  366.     gad - the gadget to check the coordinates against.
  367.  
  368.    RESULT
  369.     IsInBox - TRUE if both given coordinates was within the gadget's
  370.           outer box (X coord is between gadx and gadx+gadw,
  371.           Y coord is between gady and gady+gadh). Otherwise this
  372.           function will return FALSE.
  373.  
  374.    EXAMPLES
  375.     Assembly language:
  376.         move.l    im_MouseX(a0),d0    ; Get X and Y coordinates
  377.         move.l    mystrgad(pc),a0
  378.         move.l    GadUtilBase(pc),a6
  379.         jsr    _LVOGU_CoordsInGadBox(a6)
  380.         beq.b    .notinbox        ; Not in gadget box
  381.     
  382.         ; Do what you want to do if the coordinates are
  383.         ; within the gadget box
  384.     .notinbox:
  385.         ; Here, you may want to check for some other gadgets
  386.  
  387.  
  388.     C:
  389.         long coords;
  390.         coords = (LONG)appmsg->MouseX << 16 | appmsg->MouseY;
  391.         if (CoordsInGadBox(coords,mystrgad) = TRUE)
  392.         {
  393.             /* Do what you want to do if the coordinates
  394.                are within the gadget box */
  395.         }
  396.         else
  397.         {
  398.             /* Here, you may want to check for some other
  399.                gadgets */
  400.         }
  401. gadutil.library/GU_CountNodes                   gadutil.library/GU_CountNodes
  402.  
  403.    NAME
  404.     GU_CountNodes -- Count number of nodes in a list.
  405.  
  406.    SYNOPSIS
  407.     numnodes = GU_CountNodes(list)
  408.     D0                       A0
  409.  
  410.     ULONG GU_CountNodes(struct List *);
  411.  
  412.    FUNCTION
  413.     This function will count the number of nodes attached to a list.
  414.  
  415.    INPUTS
  416.     list - a pointer to the list to get the number of nodes in
  417.  
  418.    RESULT
  419.     numnodes - Number of nodes that was in the list for the moment.
  420.                Note that count starts from one and not from zero!
  421.  
  422.    NOTES
  423.     Use Forbid() and Permit() around a call to this function if you
  424.     are using it on a list that can change at any time (e.g. a list
  425.     that wasn't created by yourself). This function may not be accurate
  426.     when you are using it on a system list.
  427.  
  428.    SEE ALSO
  429.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  430.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_NewList(), GU_SortList()
  431. gadutil.library/GU_CreateContext             gadutil.library/GU_CreateContext
  432.  
  433.    NAME
  434.     GU_CreateContext -- Create a space for GadTools context data.
  435.  
  436.    SYNOPSIS
  437.     gad = GU_CreateContext(glistptr)
  438.     D0                     A0
  439.  
  440.     struct Gadget *GU_CreateContext(struct Gadget **);
  441.  
  442.    FUNCTION
  443.     This function is a replacement for the GadTools version. Use this
  444.     instead. This will make your program to take advantage of future
  445.     enhancements of gadutil.
  446.  
  447.     Creates a place for GadTools to store any context data it might
  448.     need for your window.  In reality, an unselectable invisible
  449.     gadget is created, with room for the context data.
  450.     This function also establishes the linkage from a glist type
  451.     pointer to the individual gadget pointers.  Call this function
  452.     before any of the other gadget creation calls.
  453.  
  454.    INPUTS
  455.  
  456.     glistptr - Address of a pointer to a Gadget, which was previously
  457.                set to NULL.  When all the gadget creation is done, you may
  458.                use that pointer as your NewWindow.FirstGadget, or
  459.                in intuition.library/AddGList(),
  460.                intuition.library/RefreshGList(), FreeGadgets(), etc.
  461.  
  462.    RESULT
  463.     gad - pointer to context gadget, or NULL if failure.
  464.  
  465.    NOTES
  466.     Look in gadtools/CreateContext() for more information.
  467.  
  468.    SEE ALSO
  469.     gadtools/CreateContext()
  470. gadutil.library/GU_CreateGadgetA             gadutil.library/GU_CreateGadgetA
  471.  
  472.    NAME
  473.     GU_CreateGadgetA -- Create a gadget with built-in hotkey support.
  474.  
  475.    SYNOPSIS
  476.     gad = CreateGadgetA(kind, prevgad, newgad, taglist)
  477.     D0,A0               D0    A0       A1      A2
  478.  
  479.     struct Gadget *GU_CreateGadgetA(ULONG, struct Gadget *,
  480.                     struct NewGadget *, struct TagItem *);
  481.  
  482.    FUNCTION
  483.     GU_CreateGadgetA() allocates and initializes a new gadget of the
  484.     specified kind, and attaches it to the previous gadget. The gadget
  485.     is created based on the supplied kind, NewGadget structure, and
  486.     tags.
  487.  
  488.     This function differs from the GadTools equivalent by supporting
  489.     some extra tags to allow the gadget to be selected using the
  490.     keyboard.
  491.  
  492.    INPUTS
  493.     kind - kind of gadget to create. One of the XXX_KIND values
  494.            defined in <libraries/gadtools.h>.
  495.  
  496.     prevgad - pointer to the previous gadget that this new gadget
  497.           should be attached to. This function will fail if
  498.           this value is NULL.
  499.  
  500.     newgad - a filled in NewGadget structure describing the desired
  501.          gadget's size, position, label, etc.
  502.  
  503.     taglist - pointer to an array of tags providing optional extra
  504.           parameters, or NULL.
  505.  
  506.    TAGS
  507.     All kinds:
  508.  
  509.     GT_Underscore - Indicates the symbol that precedes the character
  510.         in the gadget label to be underscored. This can be to
  511.         indicate keyboard equivalents for gadgets. GadUtil has
  512.         the ability to process the keyboard equivalents if some
  513.         other tags are used.
  514.  
  515.     GU_Hotkey - This tag selects the hotkey to be used as an automatic
  516.         keyboard command for the gadget. The ti_Data field should
  517.         contain the ASCII or RAWKEY code for the hotkey.
  518.         This tag may be used together with the GU_HotkeyCase and
  519.         GU_LabelHotkey. The GU_RawKey tag requires this tag.
  520.  
  521.     GU_HotkeyCase - This tag makes the keyboard command case-sensitive.
  522.         This tag may not be used with GU_RawKey.
  523.  
  524.     GU_LabelHotkey - This tag picks the hotkey from the gadget text
  525.         field in the NewGadget structure when the gadget is created.
  526.         If no key is marked with the underscore, the GU_HotKey code
  527.         will be used.
  528.  
  529.         This tag supports and requires the GT_Underscore tag. The
  530.         character that was given in the GT_Underscore tag will be
  531.         used to find the code for the hotkey.
  532.  
  533.     GU_RawKey - This tag makes the hotkey code to a RAWKEY code. All
  534.         keys on the keyboard has one rawkey code that matches the
  535.         key.
  536.  
  537.         If your program also gets VANILLAKEY events, you must be
  538.         careful when selecting the rawkey code to be used as a
  539.         keyboard shortcut for this gadget. RAWKEY events will only
  540.         be sent for special keys (such as the HELP, Control, Alt
  541.         and function keys) that don't map to a single character. 
  542.         All keys that maps to a single character will be processed
  543.         as a VANILLAKEY event.
  544.  
  545.         This tag may not be used with (and will also disable) the
  546.         GU_HotkeyCase and GU_LabelHotkey tags.
  547.  
  548.     Kind specific tags:
  549.         See the GadTools function CreateGadgetA for all other tags.
  550.  
  551.    RESULT
  552.     gad - pointer to the new gadget, or NULL if the allocation failed
  553.           or if prevgad was NULL.
  554.  
  555.    NOTES
  556.     Note that the ng_VisualInfo and ng_TextAttr fields of the NewGadget
  557.     structure must be set to valid VisualInfo and TextAttr pointers, or
  558.     this function will fail.
  559.  
  560.    SEE ALSO
  561.     GU_FreeGadgets(), GU_SetGadgetAttrsA(), GU_GetVisualInfoA(),
  562.     GU_GetIMsg(), gadtools/CreateGadgetA, <libraries/gadtools.h>
  563. gadutil.library/GU_CreateLocMenuA           gadutil.library/GU_CreateLocMenuA
  564.  
  565.    NAME
  566.     GU_CreateLocMenuA -- Create a menu with localized items.
  567.  
  568.    SYNOPSIS
  569.     menu = GU_CreateLocMenuA(newmenu, gad_info, createtags, layouttags)
  570.     D0                       A0       A1        A2             A3
  571.  
  572.     struct Menu *GU_GetLocaleStr(struct NewMenu *, APTR,
  573.                 struct TagItem *, struct TagItem *);
  574.  
  575.    FUNCTION
  576.     Create and layout a localized menu. This function replaces both
  577.     the gadtools/CreateMenusA and gadtools/LayoutMenusA functions. See
  578.     those functions for a more in-depth description of this function.
  579.  
  580.    INPUTS
  581.     newmenu - pointer to an array of initialized struct NewMenus. This
  582.           differs from the GadTools function in that, instead of
  583.           giving pointers to strings in the nm_Label and nm_CommKey
  584.           fields of the structure, you should put a string ID in the
  585.           nm_Label field of the structure. The string must be in the
  586.           format "A\x00About...". The nm_CommKey field should be left
  587.           empty.  ^^^^^^
  588.               |    |
  589.               |    |- nm_Label field for the NewMenu structure
  590.               |
  591.               |- nm_CommKey replacement. If no keyboard shortcut,
  592.                     this field MUST CONTAIN A SPACE CHAR.
  593.                     The \x00 is a NULL character.
  594.  
  595.     gad_info - the value returned from GU_LayoutGadgetsA()
  596.  
  597.     createtags - tags for the "CreateMenusA" part of this routine. All
  598.              gadtools tags are supported (directly passed to GT).
  599.  
  600.     layouttags - tags for the "LayoutMenusA" part of this routine. All
  601.              gadtools tags are supported (directly passed to GT).
  602.  
  603.    TAGS
  604.     See the gadtools functions CreateMenusA() and LayoutMenusA().
  605.  
  606.    RESULT
  607.     menu - pointer to the resulting initialized and laid out menu structure,
  608.            ready to pass to the intuition function SetMenuStrip(), or NULL for
  609.            failure.
  610.  
  611.    SEE ALSO
  612.     GU_FreeMenus(), gadtools/CreateMenusA(), gadtools/LayoutMenusA(),
  613.     gadtools/FreeMenus()
  614. gadutil.library/GU_CreateMenusA               gadutil.library/GU_CreateMenusA
  615.  
  616.    NAME
  617.     GU_CreateMenusA -- Allocate and fill out a menu structure.
  618.  
  619.    SYNOPSIS
  620.     menu = GU_CreateMenusA(newmenu, taglist)
  621.     D0                     A0       A1
  622.  
  623.     struct Menu *GU_CreateMenusA(struct NewMenu *, struct TagItem *);
  624.  
  625.    FUNCTION
  626.     CreateMenusA() allocates and initializes a complete menu
  627.     structure based on the supplied array of NewMenu structures.
  628.     Optionally, CreateMenusA() can allocate and initialize a complete
  629.     set of menu items and sub-items for a single menu title.  This
  630.     is dictated by the contents of the array of NewMenus.
  631.  
  632.     These GadTools routines are only here to make it simpler for someone
  633.     who wants to use them. This for example, is of no use if you use the
  634.     GadUtil function GU_CreateLocMenuA() to define localized (optional)
  635.     menus with automatic hotkey handlimg etc.
  636.  
  637.    INPUTS
  638.     newmenu - pointer to an array of initialized struct NewMenus.
  639.     tagList - pointer to an array of tags providing optional extra
  640.           parameters, or NULL.
  641.  
  642.    TAGS
  643.     See gadtools/CreateMenusA() for available tags.
  644.  
  645.    RESULT
  646.     menu - pointer to the resulting initialized menu structure (or
  647.               the resulting FirstItem), with all the links for menu items
  648.               and subitems in place.
  649.               The result will be NULL if CreateMenusA() could not allocate
  650.               memory for the menus, or if the NewMenu array had an
  651.               illegal arrangement (eg. NM_SUB following NM_TITLE).
  652.               (see also the GTMN_SecondaryError tag above).
  653.  
  654.    NOTES
  655.     See gadtools/CreateMenusA() for more information.
  656.  
  657.    SEE ALSO
  658.     GU_LayoutMenusA(), GU_FreeMenus(), gadtools/CreateMenusA()
  659. gadutil.library/GU_DetachList                   gadutil.library/GU_DetachList
  660.  
  661.    NAME
  662.     GU_DetachList -- Disconnect the list from a listview gadget.
  663.  
  664.    SYNOPSIS
  665.     GU_DetachList(gad, win)
  666.                   D0   A0
  667.  
  668.     VOID GU_DetachList(struct Gadget *, struct Window *);
  669.  
  670.    FUNCTION
  671.     Detach a listview's list (without visual effect).
  672.     This has to be done before you can change anything in the list,
  673.     eg add a node, delete a node etc.
  674.  
  675.     Use GU_AttachList() to put the list back to the gadget.
  676.  
  677.    INPUTS
  678.     gad - Gadget to detach list from.
  679.     win - Window that the gadget is located in.
  680.  
  681.    RESULT
  682.     none
  683.  
  684.    BUGS
  685.     none known
  686.  
  687.    SEE ALSO
  688.     GU_AddTail(), GU_ClearList(), GU_NewList(), GU_AttachList()
  689.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  690. gadutil.library/GU_DisableGadget             gadutil.library/GU_DisableGadget
  691.  
  692.    NAME
  693.     GU_DisableGadget -- Disable / Enable a gadget.
  694.  
  695.    SYNOPSIS
  696.     GU_DisableGadget(status, gadget, window)
  697.                      D0,     A0,     A1
  698.  
  699.     VOID GU_DisableGadget(BOOL, struct Gadget *, struct Window *);
  700.  
  701.    FUNCTION
  702.     Disables or enables a gadget (that supports this).
  703.  
  704.    INPUTS
  705.     status - The new status for the gadget, TRUE for disabled, FALSE for
  706.              enabled.
  707.     gadget - A pointer to the gadget to change.
  708.     window - Pointer to the window that the gadget is placed in.
  709.  
  710.    RESULT
  711.     none
  712.  
  713.    BUGS
  714.     none known
  715.  
  716.    SEE ALSO
  717. gadutil.library/GU_DrawBevelBoxA             gadutil.library/GU_DrawBevelBoxA
  718.  
  719.    NAME
  720.     GU_DrawBevelBoxA -- Draw a bevelled box.
  721.  
  722.    SYNOPSIS
  723.     GU_DrawBevelBoxA(rport, left, top, width, height, taglist)
  724.                      A0     D0    D1   D2     D3      A1
  725.  
  726.     VOID GU_DrawBevelBoxA(struct RastPort *, WORD, WORD, WORD, WORD,
  727.                   struct TagItem *);
  728.  
  729.    FUNCTION
  730.     This function renders a bevelled box of specified dimensions
  731.     and type into the supplied RastPort.
  732.  
  733.    INPUTS
  734.     rport - RastPort into which the box is to be drawn.
  735.     left - left edge of the box.
  736.     top - top edge of the box.
  737.     width - width of the box.
  738.     height - height of the box.
  739.     tagList - pointer to an array of tags providing extra parameters
  740.  
  741.    RESULT
  742.     none
  743.  
  744.    NOTES
  745.     See gadtools/DrawBevelBoxA() for more information.
  746.  
  747.    SEE ALSO
  748.     GU_GetVisualInfoA(), gadtools/DrawBevelBoxA()
  749. gadutil.library/GU_EndRefresh                   gadutil.library/GU_EndRefresh
  750.  
  751.    NAME
  752.     GU_EndRefresh -- End refreshing friendly to GadTools.
  753.  
  754.    SYNOPSIS
  755.     GU_EndRefresh(win, complete)
  756.                   A0   D0
  757.  
  758.     VOID GU_EndRefresh(struct Window *, BOOL);
  759.  
  760.    FUNCTION
  761.  
  762.     Invokes the intuition.library/EndRefresh() function in a manner
  763.     friendly to the Gadget Toolkit.  This function call permits
  764.     GadTools gadgets to refresh themselves at the correct time.
  765.     Call this function to EndRefresh() when you have used
  766.     GU_BeginRefresh().
  767.  
  768.    INPUTS
  769.     win - pointer to Window structure for which a IDCMP_REFRESHWINDOW
  770.           IDCMP event was received.
  771.     complete - TRUE when done with refreshing.
  772.  
  773.    NOTES
  774.     See gadtools/GT_EndRefresh for more information.
  775.  
  776.    SEE ALSO
  777.     GU_BeginRefresh(), gadtools/GT_EndRefresh(), intuition/EndRefresh()
  778. gadutil.library/GU_FilterIMsg                   gadutil.library/GU_FilterIMsg
  779.  
  780.    NAME
  781.     GU_FilterIMsg -- Filter an IntuiMessage through GadTools.
  782.  
  783.    SYNOPSIS
  784.     modimsg = GU_FilterIMsg(imsg)
  785.     D0                      A1
  786.  
  787.     struct IntuiMessage *GU_FilterIMsg(struct IntuiMessage *);
  788.  
  789.    FUNCTION
  790.     NOTE WELL:  Extremely few programs will actually need this function.
  791.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  792.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  793.  
  794.     GT_FilterIMsg() takes the supplied IntuiMessage and asks the
  795.     Gadget Toolkit to consider and possibly act on it.  Returns
  796.     NULL if the message was only of significance to a GadTools gadget
  797.     (i.e. not to you), else returns a pointer to a modified IDCMP
  798.     message, which may contain additional information.
  799.  
  800.     You should examine the Class, Code, and IAddress fields of
  801.     the returned message to learn what happened.  Do not make
  802.     interpretations based on the original imsg.
  803.  
  804.     You should use GT_PostFilterIMsg() to revert to the original
  805.     IntuiMessage once you are done with the modified one.
  806.  
  807.    INPUTS
  808.     imsg - an IntuiMessage you obtained from a Window's UserPort.
  809.  
  810.    RESULT
  811.     modimsg - a modified IntuiMessage, possibly with extra information
  812.               from GadTools, or NULL. When NULL, the message passed in to
  813.           the function should be sent back to Intuition via ReplyMsg().
  814.  
  815.    NOTES
  816.     See gadtools/GT_FilterIMsg() for more information.
  817.  
  818.    SEE ALSO
  819.     GU_GetIMsg(), GU_PostFilterIMsg(), gadtools/GT_FilterIMsg()
  820. gadutil.library/GU_FindNode                       gadutil.library/GU_FindNode
  821.  
  822.    NAME
  823.     GU_FindNode -- Find the node structure of a given node number
  824.  
  825.    SYNOPSIS
  826.     node = GU_FindNode(list, number)
  827.     D0,A0,SR(Z)        A0    D0
  828.  
  829.     struct Node *GU_FindNode(struct List *, WORD);
  830.  
  831.    FUNCTION
  832.     Finds a specified node in a list.
  833.  
  834.    INPUTS
  835.     list   - Struct List. The list in where to search.
  836.     number - Number of the node to find (counting from 0).
  837.  
  838.    RESULT
  839.     node  - Address to the node structure or NULL if the node wasn't
  840.             existing.
  841.  
  842.     SR(Z) - 0 for success, 1 for failure.
  843.  
  844.    BUGS
  845.     none known
  846.  
  847.    SEE ALSO
  848.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  849.     GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_NewList(), GU_SortList()
  850. gadutil.library/GU_FreeGadgets                 gadutil.library/GU_FreeGadgets
  851.  
  852.    NAME
  853.     GU_FreeGadgets -- Free a linked list of gadgets.
  854.  
  855.    SYNOPSIS
  856.     GU_FreeGadgets(glist)
  857.                    A0
  858.  
  859.     VOID GU_FreeGadgets(struct Gadget *);
  860.  
  861.    FUNCTION
  862.     Frees all gadgets found on the linked list of gadgets beginning
  863.     with the specified one. Frees all the memory that was allocated
  864.     by GU_CreateGadgetA(). This function will return safely with no
  865.     action if it recieves a NULL parameter.
  866.  
  867.     Use this function in place of gadtools/FreeGadgets().
  868.  
  869.    INPUTS
  870.     glist - pointer to the first gadget in list to be freed
  871.  
  872.    SEE ALSO
  873.     GU_CreateGadgetA() , gadtools/FreeGadgets().
  874. gadutil.library/GU_FreeInput                     gadutil.library/GU_FreeInput
  875.  
  876.    NAME
  877.     GU_FreeInput -- Unblock input to a blocked window.
  878.  
  879.    SYNOPSIS
  880.     GU_FreeInput(window)
  881.                  A0
  882.  
  883.     VOID GU_FreeInput(struct Window *);
  884.  
  885.    FUNCTION
  886.     Unblock a window's user input. Call this function after blocking
  887.     the input with GU_BlockInput().
  888.  
  889.    INPUTS
  890.     window - the window that was blocked with GU_BlockInput().
  891.  
  892.    EXAMPLE
  893.  
  894.     BlockInput(myWin);
  895.     About();
  896.     FreeInput();
  897.  
  898.     Will block the parent window for user input while displaying the
  899.     About requester of a program.
  900.  
  901.    SEE ALSO
  902.     GU_BlockInput()
  903. gadutil.library/GU_FreeLayoutGadgets     gadutil.library/GU_FreeLayoutGadgets
  904.  
  905.    NAME
  906.     GU_FreeLayoutGadgets -- Frees gadgets laid out with GU_LayoutGadgetsA().
  907.  
  908.    SYNOPSIS
  909.     GU_FreeLayoutGadgets(gad_info)
  910.                              A0
  911.  
  912.     VOID GU_FreeLayoutGadgets(APTR);
  913.  
  914.    FUNCTION
  915.     Frees gadgets laid out with LayoutGadgetsA().
  916.  
  917.    INPUTS
  918.     gad_info - The pointer returned by LayoutGadgetsA().
  919.  
  920.    RESULT
  921.     none
  922.  
  923.    SEE ALSO
  924. gadutil.library/GU_FreeMenus                     gadutil.library/GU_FreeMenus
  925.  
  926.    NAME
  927.     GU_FreeMenus -- Frees memory allocated by GU_CreateMenusA().
  928.  
  929.    SYNOPSIS
  930.     GU_FreeMenus(menu)
  931.                  A0
  932.  
  933.     VOID GU_FreeMenus(struct Menu *);
  934.  
  935.    FUNCTION
  936.     Frees the menus allocated by GU_CreateMenusA().  It is safe to
  937.     call this function with a NULL parameter.
  938.  
  939.    INPUTS
  940.     menu - pointer to menu structure (or first MenuItem) obtained
  941.            from GU_CreateMenusA().
  942.  
  943.    NOTES
  944.     See gadtools/FreeMenus() for more information.
  945.  
  946.    SEE ALSO
  947.     GU_CreateMenusA(), gadtools/FreeMenus()
  948. gadutil.library/GU_FreeVisualInfo           gadutil.library/GU_FreeVisualInfo
  949.  
  950.    NAME
  951.     GU_FreeVisualInfo -- Return any resources taken by GU_GetVisualInfoA
  952.  
  953.    SYNOPSIS
  954.     GU_FreeVisualInfo(vi)
  955.                       A0
  956.  
  957.     VOID GU_FreeVisualInfo(APTR);
  958.  
  959.    FUNCTION
  960.     FreeVisualInfo() returns any memory or other resources that
  961.     were allocated by GetVisualInfoA(). You should only call this
  962.     function once you are done with using the gadgets (i.e. after
  963.         CloseWindow()), but while the screen is still valid (i.e. before
  964.         CloseScreen() or UnlockPubScreen()).
  965.  
  966.    INPUTS
  967.     vi - pointer that was obtained by calling GetVisualInfoA(). This
  968.          value may be NULL.
  969.  
  970.    NOTES
  971.     See gadtools/FreeVisualInfo() for more information.
  972.  
  973.    SEE ALSO
  974.     GU_GetVisualInfoA(), gadtools/FreeVisualInfo()
  975. gadutil.library/GU_GadgetArrayIndex       gadutil.library/GU_GadgetArrayIndex
  976.  
  977.    NAME
  978.     GU_GadgetArrayIndex -- Get a gadget's index in the LayoutGadget array.
  979.  
  980.    SYNOPSIS
  981.     index = GU_GadgetArrayIndex(id, gadgets)
  982.     D0,D1,SR(Z)                 D0  A0
  983.  
  984.     WORD GU_GadgetArrayIndex(WORD, struct LayoutGadget *);
  985.  
  986.    FUNCTION
  987.     Get a gadget's index in the Layoutgadget structure.
  988.    INPUTS
  989.     id      - The ID of the gadget you want to find.
  990.     gadgets - The LayoutGadget array that this gadget is defined in.
  991.  
  992.    RESULT
  993.     index - The index into the LayoutGadget array of the entry with the
  994.             gadget ID you asked for. Returns -1 for failure.
  995.  
  996.     SR(Z) - Set for failure. Cleared otherwise. Probably only usable for
  997.             assembly language programmers.
  998.  
  999.    SEE ALSO
  1000. gadutil.library/GU_GetGadgetAttrsA         gadutil.library/GU_GetGadgetAttrsA
  1001.  
  1002.    NAME
  1003.     GU_GetGadgetAttrsA -- Request the attributes of a GadTools gadget.
  1004.  
  1005.    SYNOPSIS
  1006.     numProcessed = GU_GetGadgetAttrsA(gad, win, req, taglist)
  1007.     D0                                A0   A1   A2   A3
  1008.  
  1009.     LONG *GU_GetGadgetAttrsA(struct Gadget *, struct Window *,
  1010.                  struct Requester *, struct TagItem *);
  1011.  
  1012.    FUNCTION
  1013.     Retrieve the attributes of the specified gadget, according to the
  1014.     attributes chosen in the tag list.  For each entry in the tag list,
  1015.     ti_Tag identifies the attribute, and ti_Data is a pointer to
  1016.     the long variable where you wish the result to be stored.
  1017.  
  1018.    INPUTS
  1019.     gad     - Pointer to the gadget in question, may be NULL.
  1020.     win     - Pointer to the window containing the gadget
  1021.     req     - Reserved for future use, should always be NULL
  1022.     taglist - Pointer to a TagItem list
  1023.  
  1024.    RESULT
  1025.     numProcessed - The number of attributes successfully filled in.
  1026.  
  1027.    NOTES
  1028.     See gadtools/GT_GetGadgetAttrsA() for tags and examples.
  1029.  
  1030.     Requires kickstart 3.0 (V39).
  1031.  
  1032.    SEE ALSO
  1033.     GU_SetGadgetAttrsA(), gadtools/GT_GetGadgetAttrsA()
  1034. gadutil.library/GU_GetGadgetPtr               gadutil.library/GU_GetGadgetPtr
  1035.  
  1036.    NAME
  1037.     GU_GetGadgetPtr -- Get a pointer to a gadget's gadget structure.
  1038.  
  1039.    SYNOPSIS
  1040.     gad = GU_GetGadgetPtr(id, gadgets)
  1041.     D0,SR(Z)              D0  A0
  1042.  
  1043.     APTR GU_GetGadgetPtr(UWORD, struct LayoutGadget *);
  1044.  
  1045.    FUNCTION
  1046.     Find a gadget's gadget structure by giving its ID. The gadget
  1047.     pointer is always found last in the LayoutGadget structure. You
  1048.     can use this function to get that pointer.
  1049.     It is also possible to get the gadget structure by taking it
  1050.     directly from the LayoutGadget structure array, but then you
  1051.     must know exactly in which structure it is located. Assembly
  1052.     language programmers can use a PC relative pointer to get the
  1053.     gadget pointer.
  1054.     
  1055.    INPUTS
  1056.     id - the ID of the gadget to search for
  1057.  
  1058.     gadgets - a pointer to the array of LayoutGadget structures.
  1059.  
  1060.    RESULT
  1061.     gad - pointer to the requested gadget. For bevelboxes, this
  1062.           function will return a BBoxData structure.
  1063.  
  1064.    EXAMPLE
  1065.  
  1066.      Some of the LayoutGadget structures from BetterTest.c:
  1067.  
  1068.      struct LayoutGadget gadgets[] = {
  1069.     { MSG_NEXTDRIVE, NextDriveGad, StdGTTags,   NULL },
  1070.     { MSG_PREVDRIVE, PrevDriveGad, StdGTTags,   NULL },
  1071.     { MSG_DRIVE,     DriveGad,     DriveGTTags, NULL },
  1072.     { MSG_REQUESTER, ReqGad,       StdGTTags,   NULL },
  1073.     { MSG_CHECKME,   CheckBoxGad,  StdGTTags,   NULL },
  1074.     { MSG_FILENAME,  FileNameGad,  StdGTTags,   NULL },
  1075.     { -1,            NULL,         NULL,        NULL }
  1076.      };
  1077.  
  1078.     The examples should get the gadget structure of the Requester
  1079.     gadget (not assuming that ID's begin with 0).
  1080.     There is two methods you can use to get a gadgets structure:
  1081.  
  1082.     1. Use the pointer in the array directly:
  1083.  
  1084.     thegadget = gadgets[3].lg_Gadget
  1085.  
  1086.     This will only work if you know in which LayoutGadget structure
  1087.     the gadget is in.
  1088.  
  1089.     2. Use this library function:
  1090.  
  1091.     thegadget = GU_GetGadgetPtr(MSG_REQUESTER, gadgets);
  1092.  
  1093.     This will always work if all gadgets have a unique ID.
  1094.  
  1095.  
  1096.      Some of the LayoutGadget structures from BetterTest.s:
  1097.  
  1098.     gadgets:
  1099.      GADGET  MSG_NEXTDRIVE,  NextDriveGad,   StdGTTags
  1100.      GADGET  MSG_PREVDRIVE,  PrevDriveGad,   StdGTTags
  1101.      GADGET  MSG_DRIVE,      DriveGad,       DriveGTTags
  1102.      GADGET  MSG_REQUESTER,  ReqGad,         StdGTTags
  1103.      GADGET  MSG_CHECKME,    CheckBoxGad,    StdGTTags
  1104.      GADGET  MSG_FILENAME,   FileNameGad,    StdGTTags
  1105.      GADGET  -1,NULL,NULL
  1106.  
  1107.      Assembly language programmers can use three methods to get the
  1108.      pointer:
  1109.  
  1110.     1. Use the pointer in the array directly:
  1111.  
  1112.         lea.l    gadgets(pc),a0    ; Get array
  1113.         moveq.l    #lg_SIZEOF,d0    ; Get the size of the LayoutGadget
  1114.         mulu    #3,d0        ;  struct and calculate offset to
  1115.                     ;  the right structure in the array
  1116.         move.l    lg_Gadget(a0,d0.l),d0    ; Get the gadget pointer
  1117.  
  1118.     This will only work if you know in which LayoutGadget structure
  1119.     the gadget is in.
  1120.  
  1121.     2. Use this library function:
  1122.  
  1123.         lea.l    gadgets(pc),a0    ; Get array
  1124.         moveq.l    #MSG_REQUESTER,d0    ; Gadget to search for
  1125.         jsr    _LVOGU_GetGadgetPtr(a6)    ; Get gadget, result in D0
  1126.  
  1127.     This will always work if all gadgets have a unique ID.
  1128.  
  1129.     3. Use an extra label for each gadget that should be easy to
  1130.        access:
  1131.  
  1132.     gadgets:
  1133.      GADGET  MSG_NEXTDRIVE,  NextDriveGad,   StdGTTags
  1134.      GADGET  MSG_PREVDRIVE,  PrevDriveGad,   StdGTTags
  1135.      GADGET  MSG_DRIVE,      DriveGad,       DriveGTTags
  1136.      GADGET  MSG_REQUESTER,  ReqGad,         StdGTTags
  1137.     reqgad:        equ    *-4
  1138.      GADGET  MSG_CHECKME,    CheckBoxGad,    StdGTTags
  1139.      GADGET  MSG_FILENAME,   FileNameGad,    StdGTTags
  1140.     filenamegad:    equ    *-4
  1141.      GADGET  -1,NULL,NULL
  1142.  
  1143.         move.l    reqgad(pc),d0        ; Get the gadget
  1144.  
  1145.     This will always work.
  1146. gadutil.library/GU_GetIMsg                         gadutil.library/GU_GetIMsg
  1147.  
  1148.    NAME
  1149.     GU_GetIMsg -- Get an IntuiMessage, process GadTools & Hotkey events.
  1150.  
  1151.    SYNOPSIS
  1152.     imsg = GU_GetIMsg(intuiport)
  1153.     D0,A0,SR(Z)       A0
  1154.  
  1155.     struct IntuiMessage *GU_GetIMsg(struct MsgPort *);
  1156.  
  1157.    FUNCTION
  1158.     Use GU_GetIMsg() in place of the usual exec.library/GetMsg() when
  1159.     reading IntuiMessages from your window's UserPort. If needed, the
  1160.     GadTools dispatcher will be invoked, and suitable processing will
  1161.     be done for gadget actions.
  1162.     If the message is an IDCMP_VANILLAKEY or an IDCMP_RAWKEY, this
  1163.     routine will search through all gadgets    for that key, and if it is
  1164.     found, the message will change to the type of message that gadget
  1165.     is supposed to send. If the key is not used as a hotkey, the
  1166.     message will not change. 
  1167.     If there are no messages (or if the only messages are meaningful
  1168.     only to GadTools/GadUtil), NULL will be returned.
  1169.  
  1170.    INPUTS
  1171.     intuiport - the Window->UserPort of a window that is using the
  1172.         GadUtil library.
  1173.  
  1174.    RESULT
  1175.     imsg - pointer to modified IntuiMessage, or NULL if there are
  1176.            no applicable messages.
  1177.  
  1178.     SR (Z) - the zero flag will be set if there was no message. This
  1179.            is probably only useful for assembly language programmers.
  1180.  
  1181.    NOTES
  1182.     Be sure to use GU_ReplyIMsg() and not exec.library/ReplyMsg() on
  1183.     messages obtained with GU_GetIMsg().
  1184.     If you intend to do more with the resulting message than read its
  1185.     fields, act on it, and reply it, you may find GU_FilterIMsg()
  1186.     more appropriate.
  1187.  
  1188.     Starting with V39 (of the OS), this function actually returns a
  1189.     pointer to an ExtIntuiMessage structure, but the prototype was
  1190.     not changed for source code compatibility with older software.
  1191.  
  1192.    SEE ALSO
  1193.     GU_ReplyIMsg(), GU_FilterIMsg()
  1194. gadutil.library/GU_GetLocaleStr               gadutil.library/GU_GetLocaleStr
  1195.  
  1196.    NAME
  1197.     GU_GetLocaleStr -- Get a localized string from a catalog.
  1198.  
  1199.    SYNOPSIS
  1200.     string = GU_GetLocaleStr(stringID, catalog, defstrings)
  1201.     D0,A0                    D0        A0       A1
  1202.  
  1203.     STRPTR GU_GetLocaleStr(ULONG, struct Catalog *, struct AppString *);
  1204.  
  1205.    FUNCTION
  1206.     Get a localized string, or the default string, from a catalog or from
  1207.     the programs built-in strings.
  1208.  
  1209.    INPUTS
  1210.     stringID - the ID of the string to get
  1211.  
  1212.     catalog - the opened catalog for the program
  1213.  
  1214.     defstrings - an array of AppString structures, the programs built-in
  1215.              strings and ID's.
  1216.  
  1217.    RESULT
  1218.     string - the address of the localized string, or if the catalog was not
  1219.          available (or if the selected language was the programs built-
  1220.          ins), a pointer to the default string with the given ID.
  1221.  
  1222.    SEE ALSO
  1223.     GU_OpenCatalog(), GU_CloseCatalog()
  1224. gadutil.library/GU_GetVisualInfoA           gadutil.library/GU_GetVisualInfoA
  1225.  
  1226.    NAME
  1227.     GU_GetVisualInfoA -- Get information GadTools needs for visuals.
  1228.  
  1229.    SYNOPSIS
  1230.     vi = GU_GetVisualInfoA(screen, taglist)
  1231.     D0                     A0      A1
  1232.  
  1233.     APTR GU_GetVisualInfoA(struct Screen *, struct TagItem *);
  1234.  
  1235.    FUNCTION
  1236.  
  1237.     Get a pointer to a (private) block of data containing various bits
  1238.     of information that GadTools needs to ensure the best quality
  1239.     visuals.  Use the result in the NewGadget structure of any gadget
  1240.     you create, or as a parameter to the various menu calls.  Once the
  1241.     gadgets/menus are no longer needed (after the last CloseWindow()),
  1242.     call FreeVisualInfo().
  1243.  
  1244.    INPUTS
  1245.     screen - pointer to the screen you will be opening on. This parameter
  1246.          may be NULL, in which case this function fails.
  1247.     tagList - pointer to an array of tags providing optional extra
  1248.           parameters, or NULL.
  1249.  
  1250.    RESULT
  1251.     vi - pointer to private data, or NULL for failure
  1252.  
  1253.    NOTES
  1254.     See gadtools/GetVisualInfoA() for more information.
  1255.  
  1256.    SEE ALSO
  1257.     GU_FreeVisualInfo(), gadtools/FreeVisualInfo(), intuition/LockPubScreen(),
  1258.     intuition/UnlockPubScreen()
  1259. gadutil.library/GU_LayoutGadgetsA           gadutil.library/GU_LayoutGadgetsA
  1260.  
  1261.    NAME
  1262.     GU_LayoutGadgetsA -- Formats an array of GadTools gadgets.
  1263.  
  1264.    SYNOPSIS
  1265.     gad_info = GU_LayoutGadgetsA(gad_list, gadgets, screen, taglist)
  1266.     D0,A0                        A0        A1       A2      A3
  1267.  
  1268.     APTR GU_LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
  1269.         struct Screen *, struct TagItem *);
  1270.  
  1271.    FUNCTION
  1272.     Creates a laid-out gadget list from a LayoutGadget array, which
  1273.     describes each gadget you want to create. Gadgets you create can
  1274.     be any of the gadget kinds supported by GadTools, as well as any
  1275.     of the extended gadget kinds provided by GadUtil.
  1276.     The gadgets created by this routine, can easily be defined so that
  1277.     they adjust their sizes and positions to accomodate fonts of any
  1278.     size, and also adapt to different locale strings.
  1279.     
  1280.    INPUTS
  1281.     gad_list - a pointer to the gadget list pointer. This will be
  1282.            ready to pass to OpenWindowTagList() or AddGList().
  1283.  
  1284.     gadgets - an array of LayoutGadget structures. Each element in
  1285.           the array describes one of the gadgets that you will
  1286.           be creating. Each LayoutGadget structure in the array
  1287.           should be initialized as follows:
  1288.  
  1289.           lg_GadgetID - the ID for this gadget. An ID of -1
  1290.                 terminates the array. Don't use gadget ID's
  1291.                 in the range 65000(-536) to 65535 (-1). These
  1292.                 may be used internally in later versions of
  1293.                 GadUtil.
  1294.  
  1295.           lg_LayoutTags - tags that describes each gadget to
  1296.                   create. These tags is used to calculate
  1297.                   positions, sizes and other attributes
  1298.                   of the created gadgets.
  1299.  
  1300.           lg_GadToolsTags - additional tags for GadTools gadgets.
  1301.                     This would be the same set of tags that
  1302.                     you might pass to CreateGadgetA() if
  1303.                     you were using GadTools directly.
  1304.  
  1305.           lg_Gadget - the pointer to the Gadget structure created
  1306.                   for this gadget will be placed here. You
  1307.                   should initialize this field to NULL. The
  1308.                   gadget structure created should be considered
  1309.                   READ ONLY! This field will contain a pointer
  1310.                   to a struct BBoxData, if the created gadget
  1311.                   kind is a BEVELBOX_KIND or a LABEL_KIND.
  1312.  
  1313.           Assembly language programmers can use the macro GADGET:
  1314.  
  1315.             GADGET GadgetID, Gad_LayoutTags, Gad_GadToolsTags
  1316.  
  1317.     screen - a pointer to the screen that the gadgets will be created
  1318.          for. This is required, so that the layuot routines can
  1319.          get display info about the screen where the rendering
  1320.          will be done. Use LockPubScreen() to use a public screen,
  1321.          or OpenScreenTagList(), if you want to use your own screen.
  1322.  
  1323.     taglist - pointer to an array of tags providing optional extra
  1324.           parameters, or NULL.
  1325.  
  1326.                   These tags can be used here:
  1327.  
  1328.                     GU_RightExtreme (ULONG *)
  1329.                       A pointer to a longword that is used to store the
  1330.                       rightmost point that a gadget will exist in.
  1331.  
  1332.                     GU_LowerExtreme (ULONG *)
  1333.                       A pointer to a longword that is used to store the
  1334.                       lowermost point that a gadget woll exist in.
  1335.  
  1336.                     GU_Catalog (struct Catalog *)
  1337.                       A pointer to the programs translation catalog. NULL
  1338.                       indicates that the program should use the internal
  1339.                       strings. You must open the catalog by yourself (use
  1340.                       GU_OpenCatalog() or locale/OpenCatalog). The
  1341.                       GU_AppStrings tag MUST be used together with this tag.
  1342.  
  1343.                     GU_DefTextAttr (struct TextAttr *)
  1344.                       Specifies the default font to use with all gadgets. Can
  1345.                       be overridden with GU_TextAttr tag for each gadget.
  1346.  
  1347.                     GU_AppStrings (struct AppString *)
  1348.                       A pointer to an array of AppString structures. These
  1349.                       strutures contains the programs internal strings. This
  1350.                       tag must be used together with the GU_Catalog tag.
  1351.  
  1352.                     GU_BorderLeft (ULONG)
  1353.                       Size of the window's left border.
  1354.  
  1355.                     GU_BorderTop (ULONG)
  1356.                       Size of the window's top border.
  1357.  
  1358.                     GU_NoCreate (BOOL)
  1359.                       Don't create any gadgets. Useful to determine if the
  1360.                       window will fit on the screen etc.
  1361.  
  1362.                     GU_MinimumIDCMP (ULONG *)
  1363.                       A pointer to a longword that is used to store the
  1364.                       minimum required IDCMP flags, so that all gadgets will
  1365.                       work. The longword can already be initialized, and any
  1366.                       new needed IDCMP flags will be appended to that
  1367.                       longword.
  1368.  
  1369.    TAGS
  1370.  
  1371.    Tags for the gadgets lg_LayoutTags taglist. The other tags can be found in
  1372.    the autodoc to gadtools.library/CreateGadgetA().
  1373.  
  1374.    GU_GadgetKind (ULONG)
  1375.       Can be any of the standard GadTools gadget kinds, or one of the
  1376.       extensions provided by GadUtil. Currently extended types are:
  1377.  
  1378.          IMAGE_KIND
  1379.            A gadget that uses an Intuition Image structure for its
  1380.            contents. Selected and unselected states can use different
  1381.            images. The images are centered automatically.
  1382.  
  1383.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  1384.            a Gadget structure.
  1385.  
  1386.            Extra tags for IMAGE_KIND:
  1387.  
  1388.               GUIM_Image (struct Image *)
  1389.                  Image for the gadget in its unselected state. This is
  1390.                  the only required (extra) tag for IMAGE_KIND gadgets.
  1391.  
  1392.               GUIM_SelectImg (struct Image *)
  1393.                  Image for the gadget in its selected state. If this tag
  1394.                  is omitted, the selected image will be the same as the
  1395.                  unselected, and only the border and the background color
  1396.                  will change (depending on the GUIM_BOOPSILook tag).
  1397.  
  1398.               GUIM_ReadOnly (BOOL)
  1399.                  TRUE to create a read-only image gadget.
  1400.  
  1401.               GUIM_BOOPSILook (BOOL)
  1402.                  This tag will allow the programmer to select how the
  1403.                  secondary image should be shown, if only one image is
  1404.                  used for the gadget. Defaults to TRUE, which means that
  1405.                  the background color will change when the user selects
  1406.                  the gadget.
  1407.  
  1408.          DRAWER_KIND
  1409.            A "select drawer" image button. This can be used to select
  1410.            a path, but is often used to select files.
  1411.  
  1412.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  1413.            a Gadget structure.
  1414.  
  1415.          FILE_KIND
  1416.            A "select file" image button. This can be used to allow the
  1417.            user to select a file. Most programs uses the DRAWER_KIND
  1418.            for both file and path selection.
  1419.  
  1420.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  1421.            a Gadget structure.
  1422.  
  1423.          BEVELBOX_KIND
  1424.            A GadTools bevelbox. Use this to avoid the use of absolute
  1425.            sizing of bevelboxes. All bevel box kinds from OS3.0 is
  1426.            supported, even if the computer only has OS2.0.
  1427.  
  1428.            The function GU_RefreshBoxes() can be used to redraw all
  1429.            bevelboxes.
  1430.  
  1431.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  1432.            a BBoxData structure.
  1433.  
  1434.            Extra tags for BEVELBOX_KIND:
  1435.  
  1436.               GUBB_Recessed (BOOL)
  1437.                  Create a recessed ("pushed in") bevel box. Differs from
  1438.                  the GadTools tag GTBB_Recessed, in that it works with
  1439.                  both TRUE and FALSE as parameter. GadTools creates a
  1440.                  recessed box independent from the given value.
  1441.  
  1442.                  Defaults to FALSE.
  1443.  
  1444.               GUBB_FrameType (ULONG)
  1445.                  Determines what kind of box this function renders. The
  1446.                  current available alternatives are:
  1447.  
  1448.                     BFT_BUTTON - Generates a box like what is used around
  1449.                                  a GadTools BUTTON_KIND gadget.
  1450.  
  1451.                     BFT_RIDGE - Generates a box like what is used around
  1452.                                 a GadTools STRING_KIND gadget.
  1453.  
  1454.                     BFT_DROPBOX - Generates a box suitable for a standard
  1455.                                   icon drop box imagery.
  1456.  
  1457.                     BFT_HORIZBAR - Generates a horizontal shadowed line.
  1458.                                    Can also be used to draw a normal line,
  1459.                                    using 1 for the line's height.
  1460.  
  1461.                     BFT_VERTBAR - Generates a vertical shadowed line. Can
  1462.                                   also be used to draw a normal line, using
  1463.                                   1 for the line's width.
  1464.  
  1465.                  Defaults to BFT_BUTTON.
  1466.  
  1467.               GUBB_TextColor (ULONG)
  1468.                  Selects which color to print the title text in. Only useful
  1469.                  for a bevelbox with a title. Defaults to the color of the
  1470.                  TEXTPEN.
  1471.  
  1472.               GUBB_TextPen (ULONG)
  1473.                  Selects which pen to print the title text in. Only
  1474.                  useful for a bevelbox with a title. Defaults to TEXTPEN.
  1475.                  This tag overrides the GUBB_TextColor tag.
  1476.  
  1477.               GUBB_Flags (ULONG)
  1478.                  Flags for text placement, text shadowing and 3D text:
  1479.  
  1480.                  Y-pos flags
  1481.                  ~~~~~~~~~~~
  1482.                     BB_TEXT_ABOVE - Places the bevel box text above the upper
  1483.                                     border of the box           ___Example___
  1484.  
  1485.                     BB_TEXT_IN    - Places the bevel box text at the upper
  1486.                                     border of the box           ---Example---
  1487.  
  1488.                     BB_TEXT_BELOW - Places the bevel box text below the upper
  1489.                                     border of the box           ___       ___
  1490.                                                                    Example
  1491.                  X-pos flags
  1492.                  ~~~~~~~~~~~
  1493.                     BB_TEXT_CENTER - Places the bevel box text in the middle
  1494.                                      of the upper border        ---Example---
  1495.  
  1496.                     BB_TEXT_LEFT   - Places the bevel box text 8 pixels from
  1497.                                      the left edge of the box   -Example-----
  1498.  
  1499.                     BB_TEXT_RIGHT  - Places the bevel box text 8 pixels from
  1500.                                      the right edge of the box  -----Example-
  1501.  
  1502.                  Combined flags
  1503.                  ~~~~~~~~~~~~~~
  1504.                     BB_TEXT_ABOVE_CENTER - BB_TEXT_ABOVE + BB_TEXT_CENTER
  1505.                     BB_TEXT_ABOVE_LEFT   - BB_TEXT_ABOVE + BB_TEXT_LEFT
  1506.                     BB_TEXT_ABOVE_RIGHT  - BB_TEXT_ABOVE + BB_TEXT_RIGHT
  1507.  
  1508.                     BB_TEXT_IN_CENTER    - BB_TEXT_IN + BB_TEXT_CENTER
  1509.                     BB_TEXT_IN_LEFT      - BB_TEXT_IN + BB_TEXT_LEFT
  1510.                     BB_TEXT_IN_RIGHT     - BB_TEXT_IN + BB_TEXT_RIGHT
  1511.  
  1512.                     BB_TEXT_BELOW_CENTER - BB_TEXT_BELOW + BB_TEXT_CENTER
  1513.                     BB_TEXT_BELOW_LEFT   - BB_TEXT_BELOW + BB_TEXT_LEFT
  1514.                     BB_TEXT_BELOW_RIGHT  - BB_TEXT_BELOW + BB_TEXT_RIGHT
  1515.  
  1516.                  Default is BB_TEXT_ABOVE|BB_TEXT_CENTER. Combine the x and y
  1517.                  position flags by OR:ing them together. Don't combine two X
  1518.                  or two Y flags together.
  1519.                 
  1520.                  Shadow placement flags
  1521.                  ~~~~~~~~~~~~~~~~~~~~~~
  1522.                     BB_SHADOW_DR - Places the bevel box text shadow one pixel
  1523.                                    below and to the right of the text. 
  1524.  
  1525.                     BB_SHADOW_UR - Places the bevel box text shadow one pixel
  1526.                                    above and to the right of the text. 
  1527.  
  1528.                     BB_SHADOW_DL - Places the bevel box text shadow one pixel
  1529.                                    below and to the left of the text. 
  1530.  
  1531.                     BB_SHADOW_UL - Places the bevel box text shadow one pixel
  1532.                                    above and to the left of the text. 
  1533.  
  1534.                     BB_SUNAT_UL  - Another name for BB_SHADOW_DR
  1535.                     BB_SUNAT_DL  - Another name for BB_SHADOW_UR
  1536.                     BB_SUNAT_UR  - Another name for BB_SHADOW_DL
  1537.                     BB_SUNAT_DR  - Another name for BB_SHADOW_UL
  1538.  
  1539.                  Default is BB_SHADOW_DR (BB_SUNAT_UL).
  1540.  
  1541.                     BB_3DTEXT    - This flag can be used in place of the tag
  1542.                                    GUBB_3DText, TRUE
  1543.  
  1544.               GUBB_3DText (BOOL)
  1545.                  Enables the shadow on the bevel box text. This tag must be
  1546.                  used if GUBB_ShadowColor or GUBB_ShadowPen isn't used.
  1547.                  Another way to enable 3D text is to set the flag BB_3DTEXT
  1548.                  in the GUBB_Flags tag.
  1549.  
  1550.               GUBB_ShadowColor (ULONG)
  1551.                  Selects which color to print the shadow text in. Only useful
  1552.                  for a bevelbox with a title. Defaults to the color of the
  1553.                  SHADOWPEN.
  1554.  
  1555.               GUBB_ShadowPen (ULONG)
  1556.                  Selects which pen to print the shadow text in. Only useful
  1557.                  for a bevelbox with a title. Defaults to SHADOWPEN.
  1558.                  This tag overrides the GUBB_ShadowColor tag.
  1559.  
  1560.          PROGRESS_KIND
  1561.            Gadget used to display a value out of a total. Can be used to
  1562.            display the progress of a search, a diskcopy or anything else.
  1563.  
  1564.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  1565.            a ProgressGad structure.
  1566.  
  1567.            Extra tags for PROGRESS_KIND:
  1568.  
  1569.               GUPR_FillColor (ULONG)
  1570.                  Selects which color to use to paint the current value of
  1571.                  the progress requester with. Defaults to the color of the
  1572.                  FILLPEN.
  1573.  
  1574.               GUPR_FillPen (ULONG)
  1575.                  Selects which pen to use to paint the current value of
  1576.                  the progress requester with. Defaults to the FILLPEN.
  1577.                  This tag overrides the GUPR_FillColor tag.
  1578.  
  1579.               GUPR_BackColor (ULONG)
  1580.                  Selects which color to fill the background of the progress
  1581.                  requester with. Defaults to the color of the BACKGROUNDPEN.
  1582.  
  1583.               GUPR_BackPen (ULONG)
  1584.                  Selects which pen to fill the background of the progress
  1585.                  requester with. Defaults to the BACKGROUNDPEN.
  1586.                  This tag overrides the GUPR_BackColor tag.
  1587.  
  1588.               GUPR_Current (ULONG)
  1589.                  The initial current value of the progress requester. The
  1590.                  gadget's current value may be changed later by directly
  1591.                  modifying the pg_Current field of the ProgressGad structure.
  1592.                  Use GU_UpdateProgress to redraw the progress requester with
  1593.                  the new value. The pg_Current field must not be larger than
  1594.                  4.294.967.295 / the width of the progress gadget. A "normal"
  1595.                  width of 410 pixels allows a current value of 10.737.418.
  1596.          Defaults to 0.
  1597.  
  1598.               GUPR_Total (ULONG)
  1599.                  The initial total value of the progress requester. The
  1600.                  gadget's total value may be changed later by directly
  1601.                  modifying the pg_Total field of the ProgressGad structure.
  1602.                  Use GU_UpdateProgress() to redraw the progress requester with
  1603.                  the new value. The total value can be as large as a longword
  1604.                  allows (4.294.967.295), but you can't display a current value
  1605.                  larger than 4.294.967.295 / the width of the progress gadget.
  1606.          Defaults to 100.
  1607.  
  1608.          LABEL_KIND
  1609.            A text label. Use this to avoid the use of absolute placement
  1610.            of text that you print into the window. Supports the most of
  1611.            the text placement and shadow flags for the BEVELBOX_KIND.
  1612.  
  1613.            The function GU_RefreshBoxes() can be used to redraw all
  1614.            text created by LABEL_KIND gadgets.
  1615.  
  1616.            The value in the LayoutGadget's lg_Gadget field is a pointer to
  1617.            a BBoxData structure.
  1618.  
  1619.            Extra tags for LABEL_KIND:
  1620.  
  1621.               GULB_TextColor (ULONG)
  1622.                  Selects which color to print the text in. Defaults to the
  1623.                  color of the TEXTPEN.
  1624.  
  1625.               GULB_TextPen (ULONG)
  1626.                  Selects which pen to print the text in. Defaults to TEXTPEN.
  1627.                  This tag overrides the GULB_TextColor tag.
  1628.  
  1629.               GULB_Flags (ULONG)
  1630.                  Flags for text placement, text shadowing and 3D text:
  1631.  
  1632.                  ___1_____2_____3___
  1633.                  |_____|_____|_____| A
  1634.                  |_____|_____|_____| B 
  1635.                  |_____|_____|_____| C
  1636.                  
  1637.                  Y-pos flags
  1638.                  ~~~~~~~~~~~
  1639.                     LB_TEXT_TOP    - Places the topmost point of the text below
  1640.                                      the upper border of the box (row A)
  1641.  
  1642.                     LB_TEXT_MIDDLE - Places the text centered in the box, not
  1643.                                      counting in the part of the text that is
  1644.                                      below the font's baseline (row B)
  1645.  
  1646.                     LB_TEXT_BOTTOM - Places the text at the bottom of the box.
  1647.                                      Any part of the text that is below the
  1648.                                      baseline will be below the box (row C)
  1649.  
  1650.                  X-pos flags
  1651.                  ~~~~~~~~~~~
  1652.                     LB_TEXT_CENTER - Places the text centered on the width of
  1653.                                      the box (column 2).
  1654.  
  1655.                     LB_TEXT_LEFT   - Places the text left adjusted in the box
  1656.                                      (column 1)
  1657.  
  1658.                     LB_TEXT_RIGHT  - Places the text right adjusted in the box
  1659.                                      (column 3)
  1660.  
  1661.                  Combined flags
  1662.                  ~~~~~~~~~~~~~~
  1663.                     LB_TEXT_TOP_CENTER    - LB_TEXT_TOP + LB_TEXT_CENTER
  1664.                     LB_TEXT_TOP_LEFT      - LB_TEXT_TOP + LB_TEXT_LEFT
  1665.                     LB_TEXT_TOP_RIGHT     - LB_TEXT_TOP + LB_TEXT_RIGHT
  1666.  
  1667.                     LB_TEXT_MIDDLE_CENTER - LB_TEXT_MIDDLE + LB_TEXT_CENTER
  1668.                     LB_TEXT_MIDDLE_LEFT   - LB_TEXT_MIDDLE + LB_TEXT_LEFT
  1669.                     LB_TEXT_MIDDLE_RIGHT  - LB_TEXT_MIDDLE + LB_TEXT_RIGHT
  1670.  
  1671.                     LB_TEXT_BOTTOM_CENTER - LB_TEXT_BOTTOM + LB_TEXT_CENTER
  1672.                     LB_TEXT_BOTTOM_LEFT   - LB_TEXT_BOTTOM + LB_TEXT_LEFT
  1673.                     LB_TEXT_BOTTOM_RIGHT  - LB_TEXT_BOTTOM + LB_TEXT_RIGHT
  1674.  
  1675.                  Default is LB_TEXT_TOP|LB_TEXT_CENTER. Combine the x and y
  1676.                  position flags by OR:ing them together. Don't combine two X
  1677.                  or two Y flags together.
  1678.                 
  1679.                  Shadow placement flags
  1680.                  ~~~~~~~~~~~~~~~~~~~~~~
  1681.                     LB_SHADOW_DR - Places the bevel box text shadow one pixel
  1682.                                    below and to the right of the text. 
  1683.  
  1684.                     LB_SHADOW_UR - Places the bevel box text shadow one pixel
  1685.                                    above and to the right of the text. 
  1686.  
  1687.                     LB_SHADOW_DL - Places the bevel box text shadow one pixel
  1688.                                    below and to the left of the text. 
  1689.  
  1690.                     LB_SHADOW_UL - Places the bevel box text shadow one pixel
  1691.                                    above and to the left of the text. 
  1692.  
  1693.                     LB_SUNAT_UL  - Another name for LB_SHADOW_DR
  1694.                     LB_SUNAT_DL  - Another name for LB_SHADOW_UR
  1695.                     LB_SUNAT_UR  - Another name for LB_SHADOW_DL
  1696.                     LB_SUNAT_DR  - Another name for LB_SHADOW_UL
  1697.  
  1698.                  Default is LB_SHADOW_DR (LB_SUNAT_UL).
  1699.  
  1700.                     LB_3DTEXT    - This flag can be used in place of the tag
  1701.                                    GULB_3DText, TRUE
  1702.  
  1703.               GULB_3DText (BOOL)
  1704.                  Enables the shadow on the text. This tag must be used if
  1705.                  GULB_ShadowColor or GULB_ShadowPen isn't used. Another
  1706.                  way to enable 3D text is to set the flag LB_3DTEXT in the
  1707.                  GULB_Flags tag.
  1708.  
  1709.               GULB_ShadowColor (ULONG)
  1710.                  Selects which color to print the shadow text in. Defaults to
  1711.                  the color of the SHADOWPEN.
  1712.  
  1713.               GULB_ShadowPen (ULONG)
  1714.                  Selects which pen to print the shadow text in. Defaults to
  1715.                  SHADOWPEN. This tag overrides the GULB_ShadowColor tag.
  1716.  
  1717.          Changed tags, and additions to GadTools:
  1718.  
  1719.          LISTVIEW_KIND
  1720.  
  1721.            GTLV_ShowSelected (UWORD id)
  1722.  
  1723.               This tag was changed, so that you don't have to create the
  1724.               string gadget before all other gadgets. The difference from
  1725.               this tag in GadTools, is that we now have to give the ID of
  1726.               the string gadget to use to show the selected item.
  1727.  
  1728.               An example of a valid (and probably most useful) gadget to
  1729.               use for GTLV_ShowSelected:
  1730.  
  1731.               ShowSelGad:
  1732.                   dc.l    GU_GadgetKind,  STRING_KIND,    GU_AutoHeight,  4
  1733.                   dc.l    GU_DupeWidth,   GAD_LISTVIEW,   GU_GadgetText,  NULL
  1734.                   dc.l    TAG_DONE
  1735.  
  1736.               This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
  1737.               array.
  1738.  
  1739.               Special:
  1740.  
  1741.               ti_Data = -1    Creates a read-only gadget below the listview,
  1742.                               same as for GTLV_ShowSelected, 0  for GadTools.
  1743.  
  1744.               ti_Data =  x    Gadget ID for the gadget that the selected item
  1745.                               should be displayed in. Same as GadTools reaction
  1746.                               on a gadget pointer in ti_Data.
  1747.  
  1748.               This gadget's ti_Data field will be changed during the creation
  1749.               of the gadget, but will be changed back before GU_LayoutGadgets
  1750.               returns.
  1751.  
  1752.          MX_KIND
  1753.           The gng_GadgetText field in the NewGadget structure can be used
  1754.           even with MX_KIND gadgets. This should have been included in
  1755.           GadTools. The gadget text will always be placed ABOVE the gadget,
  1756.           on the same side as the other texts for the gadget. Positions are
  1757.           checked against WBPattern & SerialPrefs to get them "right". The
  1758.           GU_GadgetText and GU_LocaleText tags are used to access this field.
  1759.  
  1760.  
  1761.    Tags for all gadget kinds:
  1762.  
  1763.    Gadget width control:
  1764.  
  1765.       GU_Width (UWORD wid)
  1766.          Absolute width of the gadget. Not recommended to use for other
  1767.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  1768.  
  1769.       GU_DupeWidth (UWORD id)
  1770.          Duplicate the width of another gadget.
  1771.  
  1772.       GU_AutoWidth (WORD add)
  1773.          Width = length of text label + ti_Data. For CYCLE_KIND gadgets,
  1774.      the gadget width will be calculated by checking the length of
  1775.      all alternatives and using the one that is widest + 26 as width.
  1776.  
  1777.       GU_Columns (UWORD numcols)
  1778.          Set the gadget width so that approximately ti_Data columns of
  1779.          text will fit.
  1780.  
  1781.       GU_AddWidth (WORD add)
  1782.          Add ti_Data to the total width calculation.
  1783.  
  1784.       GU_MinWidth (UWORD wid)
  1785.          Make the gadget at least ti_Data pixels wide.
  1786.  
  1787.       GU_MaxWidth (UWORD wid)
  1788.          Make the gadget at most ti_Data pixels wide.
  1789.  
  1790.       GU_AddWidChar (WORD chars)
  1791.          Add the length of ti_Data characters to the total width calculation.
  1792.  
  1793.       GU_FractWidth (LONG parts)
  1794.      Divide or multiply the gadget's width with ti_Data. A positive
  1795.      value divides the gadget's width by the ti_Data, a negative ti_Data
  1796.      multiplies the gadget's width with ti_Data.
  1797.  
  1798.     Gadget height control:
  1799.  
  1800.       GU_Height (UWORD hei)
  1801.          Absolute height of the gadget. Not recommended to use for other
  1802.          gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  1803.         
  1804.       GU_DupeHeight (UWORD id)
  1805.          Duplicate the height of another gadget.
  1806.  
  1807.       GU_AutoHeight (WORD add)
  1808.          Height = height of the gadget's font + ti_Data. This tag doesn't
  1809.          work as it should with MX_KIND gadgets. Will be fixed later.
  1810.          Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
  1811.  
  1812.       GU_HeightFactor (UWORD numlines)
  1813.          Set the gadget height to approximately ti_Data lines.
  1814.  
  1815.       GU_AddHeight (WORD add)
  1816.          Add ti_Data to the total height calculation.
  1817.  
  1818.       GU_MinHeight (UWORD wid)
  1819.          Make the gadget at least ti_Data pixels high.
  1820.  
  1821.       GU_MaxHeight (UWORD wid)
  1822.          Make the gadget at most ti_Data pixels high.
  1823.  
  1824.       GU_AddHeiLines (WORD numlines)
  1825.          Add the height of ti_Data/2 lines to the final height calculation.
  1826.          The numlines argument is given in units of 1/2 lines to get
  1827.          better resolution (ti_Data of 4 means that the height of 2
  1828.          lines should be added).
  1829.  
  1830.       GU_FractHeight (LONG parts)
  1831.      Divide or multiply the gadget's height with ti_Data. A positive
  1832.      value divides the gadget's height by the ti_Data, a negative ti_Data
  1833.      multiplies the gadget's height with ti_Data.
  1834.  
  1835.    Gadget top edge control:
  1836.  
  1837.       GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
  1838.       allows any bottom edge control tag to adjust the height, so that both
  1839.       top and bottom edges will be correct.
  1840.  
  1841.       GU_Top (UWORD ypos)
  1842.          Absolute top edge of the gadget. Not recommended to use for other
  1843.          gadgets than the top-most gadgets.
  1844.  
  1845.       GU_TopRel (UWORD id)
  1846.          Make the top edge relative to another gadgets bottom edge. This
  1847.          gadget will be placed BELOW the given gadget.
  1848.  
  1849.       GU_AddTop (WORD add)
  1850.          Add ti_Data to the final top edge calculation.
  1851.  
  1852.       GU_AlignTop (UWORD id)
  1853.          Align the top edge of the gadget with another gadgets top edge.
  1854.  
  1855.       GU_AdjustTop (WORD add)
  1856.          Add the height of the text font + ti_Data to the top edge.
  1857.  
  1858.       GU_AddTopLines (WORD numlines)
  1859.          Add the height of ti_Data/2 lines to the final top edge. The
  1860.          numlines argument is given in units of 1/2 lines to get better
  1861.          resolution (ti_Data of 4 means that the height of 2 lines
  1862.          should be added).
  1863.  
  1864.    Gadget bottom edge control:
  1865.  
  1866.       GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
  1867.       gadget, and allows any top edge control tag to adjust the height, so that
  1868.       both top and bottom edges will be correct.
  1869.  
  1870.       GU_Bottom (UWORD ypos)
  1871.          Absolute bottom edge of the gadget. Not recommended to use for other
  1872.          gadgets than the bottom-most gadgets. Should not be necessary to use
  1873.          at all.
  1874.  
  1875.       GU_BottomRel (UWORD id)
  1876.          Make the bottom edge relative to another gadgets top edge. This
  1877.          gadget will be placed ABOVE the given gadget.
  1878.  
  1879.       GU_AddBottom (WORD add)
  1880.          Add ti_Data to the final bottom edge calculation.
  1881.  
  1882.       GU_AlignBottom (UWORD id)
  1883.          Align the bottom edge of the gadget with another gadgets bottom edge.
  1884.  
  1885.       GU_AdjustBottom (WORD add)
  1886.          Subtract the height of the gadget's font + ti_Data from the top edge.
  1887.          This will move the gadget UPWARDS (ti_Data + font height) pixels.
  1888.  
  1889.    Gadget left edge control:
  1890.  
  1891.       GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
  1892.       and allows any right edge control tag to adjust the width, so that both
  1893.       left and right edges will be correct.
  1894.  
  1895.       GU_Left (UWORD xpos)
  1896.          Absoulute left edge of the gadget. Not recommended to use for other
  1897.          gadgets than the left-most gadgets.
  1898.  
  1899.       GU_LeftRel (UWORD id)
  1900.          Make the left edge relative to another gadgets right edge. This
  1901.          gadget will be placed TO THE RIGHT of the given gadget.
  1902.  
  1903.       GU_AddLeft (WORD add)
  1904.          Add ti_Data to the final left edge calculation.
  1905.  
  1906.       GU_AlignLeft (UWORD id)
  1907.          Align the left edge of the gadget with another gadgets left edge.
  1908.  
  1909.       GU_AdjustLeft (WORD add)
  1910.          Add the width of the gadget label + ti_Data to the left edge.
  1911.  
  1912.       GU_AddLeftChar (WORD chars)
  1913.          Add the length of ti_Data characters to the left edge.
  1914.  
  1915.    Gadget right edge control:
  1916.  
  1917.       GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
  1918.       gadget, and allows any left edge control tag to adjust the width, so
  1919.       that both left and right edges will be correct.
  1920.  
  1921.       GU_Right (UWORD xpos)
  1922.          Absoulute right edge of the gadget. Not recommended to use for other
  1923.          gadgets than the right-most gadgets. Should not be necessary to use
  1924.          at all.
  1925.  
  1926.       GU_RightRel (UWORD id)
  1927.          Make the right edge relative to another gadgets left edge. This
  1928.          gadget will be placed TO THE LEFT of the given gadget.
  1929.  
  1930.       GU_AddRight (WORD add)
  1931.          Add ti_Data to the final right edge calculation.
  1932.  
  1933.       GU_AlignRight (UWORD id)
  1934.          Align the right edge of the gadget with another gadgets right edge.
  1935.  
  1936.       GU_AdjustRight (WORD add)
  1937.          Add the width of the gadget label + ti_Data to the left edge.
  1938.  
  1939.     Other tags:
  1940.  
  1941.       GU_ToggleSelect (BOOL)
  1942.          Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
  1943.          gadgets.
  1944.  
  1945.       GU_Selected (BOOL)
  1946.          Set the initial value of a toggle select gadget.
  1947.  
  1948.       GU_Hotkey (CHAR)
  1949.          Hotkey that should simulate a press (release) of a gadget.
  1950.  
  1951.       GU_HotkeyCase (BOOL)
  1952.          Make the hotkey case-sensitive. Default is not case sensitive.
  1953.  
  1954.       GU_LabelHotkey (BOOL)
  1955.          Get the hotkey directly from the gadget's label. The hotkey can
  1956.          be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
  1957.  
  1958.       GU_RawKey (BYTE)
  1959.          Use a rawkey as a gadget hotkey. May not be case-sensitive.
  1960.         
  1961.       GU_HelpGadget (ULONG)
  1962.          GadgetID of the TEXT_KIND or the STRING_KIND to show the gadget's
  1963.          help text in.
  1964.  
  1965.       GU_HelpText (UBYTE *)
  1966.          The text that is shown in the help gadget (GU_HelpGadget) when the
  1967.          mouse pointer is placed on the gadget.
  1968.  
  1969.       GU_LocaleHelp (ULONG stringid)
  1970.          Get gadget help text from a catalog. This makes it easy to create
  1971.          localized help strings in the program.
  1972.  
  1973.    Tags that gives access to other fields in the NewGadget structure:
  1974.  
  1975.       GU_GadgetText (UBYTE *)
  1976.          A pointer to the gadget's label. Will be copied directly into the
  1977.          gng_GadgetText field of the NewGadget structure.
  1978.  
  1979.       GU_TextAttr (struct TextAttr *)
  1980.          A pointer to an initialized TextAttr structure (to select the font).
  1981.          Will be copied directly into the gng_TextAttr field of the NewGadget
  1982.          structure.
  1983.  
  1984.       GU_Flags (ULONG)
  1985.          Gadget flags. Currently available flags are as for GadTools, but
  1986.          here is a short list of them:
  1987.  
  1988.          PLACETEXT_LEFT - Place the gadget label right aligned on the left
  1989.                           side of the gadget.
  1990.  
  1991.          PLACETEXT_RIGHT - Place the gadget label left aligned on the right
  1992.                            side of the gadget.
  1993.  
  1994.          PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
  1995.  
  1996.          PLACETEXT_BELOW - Place the gadget label centered below the gadget.
  1997.  
  1998.          PLACETEXT_IN - Place the gadget label centered inside the gadget.
  1999.  
  2000.          NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
  2001.  
  2002.       *** GU_UserData (APTR) *** REMOVED in v37.7 ***
  2003.  
  2004.       GU_LocaleText (ULONG stringid)
  2005.          Get gadget label from a catalog. This allows easy localization of
  2006.          all new programs.
  2007.  
  2008.  
  2009.    RESULT
  2010.     gad_info - a pointer to a private structure. You must keep this
  2011.            value and pass it to GU_FreeLayoutGadgets() later on
  2012.            in order to free up all resources used by your gadgets.
  2013.            This pointer is also used in a lot of other functions
  2014.            in this library.
  2015.  
  2016.    NOTES
  2017.     You must be careful with the taglist in the lg_LayoutTags field.
  2018.     Tags are processed sequentally in the order you give them in, and
  2019.     if a tag references another gadget (eg. the GL_TopRel tag), then
  2020.     processing of the current gadget halts while the referenced gadget
  2021.     is processed (if it has not already been processed). Problems can
  2022.     occur if this gadget refers back to the original gadget that
  2023.     referenced if, if it is referring to a field that has not yet been
  2024.     processed in that gadget.
  2025.  
  2026.         Also note that you do not have to specify any tags that do not
  2027.         change from gadget to gadget. Just be sure that you know in which
  2028.     order the gadgets are processed (eg. relatives etc).
  2029.  
  2030.     Another thing to note, is that we have tried to make the processing
  2031.     of position and width / height tags as usable as possible, what I
  2032.     mean with this, is that if you eg first define the left edge and
  2033.     then define the right edge, the width will change. BUT, there are
  2034.     special cases when this isn't true. This is because we have tried
  2035.     out this and decided that this was the best way to do it.
  2036.  
  2037.     Here comes some examples of the special cases;
  2038.  
  2039.     dc.l    GU_AlignLeft, GAD_1    ; Left edge aligned with GAD_1's left.
  2040.     dc.l    GU_AlignRight, GAD_2    ; This stretches the gadget, so that
  2041.                     ; both the left and right edges are
  2042.                     ; positioned as defined.
  2043.     ; Then, if we want to move the right edge 2 pixels right, and the left
  2044.     ; edge two pixels right, we might try this:
  2045.  
  2046.     dc.l    GU_AddLeft, -2        ; This works as we want, it moves the
  2047.                     ; left edge to the right place, but it
  2048.                     ; also moves the whole gadget two
  2049.                     ; pixels left..
  2050.  
  2051.     dc.l    GU_AddRight, 2        ; <- This is a common mistake. This
  2052.                     ; moves the whole gadget to the right.
  2053.                     ; Ie. it is moved back to the old
  2054.                     ; position, not as we wanted...
  2055.  
  2056.     ; But if we replace the previous line with the following;
  2057.  
  2058.     dc.l    GU_AddWith,4        ; This works just as we wanted it to.
  2059.                     ; Now the gadget should be 4 pixels
  2060.                     ; wider, two to the left and two to
  2061.                     ; the right.
  2062.  
  2063.     The same goes for GU_AddHeight and GU_AddBottom etc.
  2064.  
  2065.     This is actually a feature. Sometimes you might want to move the whole
  2066.     button, so we made it work this way.
  2067.  
  2068.  
  2069.    SEE ALSO
  2070.     GU_FreeLayoutGadgets(), GU_CreateGadgetA(), gadtools/CreateGadgetA()
  2071.     GU_RefreshWindow(), GU_RefreshBoxes(), GU_UpdateProgress()
  2072. gadutil.library/GU_LayoutMenuItemsA       gadutil.library/GU_LayoutMenuItemsA
  2073.  
  2074.    NAME
  2075.     GU_LayoutMenuItemsA -- Position all the menu items.
  2076.  
  2077.    SYNOPSIS
  2078.     success = GU_LayoutMenuItemsA(menuitem, vi, tags)
  2079.     D0                            A0        A1  A2
  2080.  
  2081.     BOOL GU_LayoutMenuItemsA(struct MenuItem *, APTR, struct TagItem *);
  2082.  
  2083.    FUNCTION
  2084.     Lays out all the menu items and sub-items according to
  2085.     the supplied visual information and tag parameters. You would use this
  2086.     if you used CreateMenusA() to make a single menu-pane (with sub-items,
  2087.     if any), instead of a whole menu strip.
  2088.     This routine attempts to columnize and/or shift the MenuItems in
  2089.     the event that a menu would be too tall or too wide.
  2090.  
  2091.    INPUTS
  2092.     menuitem - Pointer to the first MenuItem in a linked list of items.
  2093.     vi       - Pointer returned by GU_GetVisualInfoA().
  2094.     tags     - Pointer to an array of tags providing optional extra
  2095.                information.
  2096.  
  2097.    TAGS
  2098.     See gadtools/LayoutMenuItemsA() for tags.
  2099.  
  2100.    RESULT
  2101.     success  - TRUE if successfull, FALSE otherwise.
  2102.  
  2103.    SEE ALSO
  2104.     GU_CreateMenusA(), GU_GetVisualInfoA(), gadtools/LayoutMenuItemsA()
  2105. gadutil.library/GU_LayoutMenusA       gadutil.library/GU_LayoutMenusA
  2106.  
  2107.    NAME
  2108.     GU_LayoutMenusA -- Position all the menus and menu items.
  2109.  
  2110.    SYNOPSIS
  2111.     success = GU_LayoutMenusA(menu, vi, taglist)
  2112.     D0                        A0    A1  A2
  2113.  
  2114.     BOOL GU_LayoutMenusA(struct Menu *, APTR, struct TagItem *);
  2115.  
  2116.    FUNCTION
  2117.     Lays out all the menus, menu items and sub-items in the supplied
  2118.     menu according to the supplied visual information and tag parameters.
  2119.     This routine attempts to columnize and/or shift the MenuItems in
  2120.     the event that a menu would be too tall or too wide.
  2121.  
  2122.     These GadTools routines are only here to make it simpler for someone
  2123.     who wants to use them. This for example, is of no use if you use the
  2124.     GadUtil function GU_CreateLocMenuA() to define localized (optional)
  2125.     menus with automatic hotkey handlimg etc.
  2126.  
  2127.    INPUTS
  2128.     menu    - Pointer to menu obtained from GU_CreateMenusA() or
  2129.               GU_CreateLocMenuA().
  2130.     vi      - Pointer returned by GU_GetVisualInfoA.
  2131.     taglist - Pointer to an array of tags providing optional extra
  2132.               parameters.
  2133.  
  2134.    TAGS
  2135.     See gadtools/LayoutMenusA() for tags.
  2136.  
  2137.    RESULT
  2138.     success - TRUE if successfull, FALSE otherwise.
  2139.  
  2140.    NOTES
  2141.     See gadtools/LayoutMenusA() for more information.
  2142.  
  2143.    SEE ALSO
  2144.     GU_CreateMenusA(), GU_GetVisualInfoA(), gadtools/LayoutMenusA()
  2145. gadutil.library/GU_NewList                         gadutil.library/GU_NewList
  2146.  
  2147.    NAME
  2148.     GU_NewList -- Initialize a list header for use.
  2149.  
  2150.    SYNOPSIS
  2151.     GU_NewList(list)
  2152.                A0
  2153.  
  2154.     VOID GU_NewList(struct List *);
  2155.  
  2156.    FUNCTION
  2157.     This initializes a list header for use. Much easier than to do it
  2158.     by hand.
  2159.  
  2160.    INPUTS
  2161.     list - Struct List.
  2162.  
  2163.    RESULT
  2164.     none
  2165.  
  2166.    BUGS
  2167.     none known
  2168.  
  2169.    SEE ALSO
  2170.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  2171.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_CountNodes(), GU_SortList()
  2172. gadutil.library/GU_NodeDown                       gadutil.library/GU_NodeDown
  2173.  
  2174.    NAME
  2175.     GU_NodeDown -- Move a node one step towards the end of the list
  2176.  
  2177.    SYNOPSIS
  2178.     success = GU_NodeDown(node, list)
  2179.     D0,SR(Z)              A0    A1
  2180.  
  2181.     BOOL GU_NodeDown(struct Node *, struct List *);
  2182.  
  2183.    FUNCTION
  2184.     Move a node one step downwards in a list. To do the opposite, see
  2185.     GU_NodeUp().
  2186.  
  2187.    INPUTS
  2188.     node - The node to move.
  2189.     list - The list that the node is a part of.
  2190.  
  2191.    RESULT
  2192.     success - TRUE if the node could be moved, else FALSE.
  2193.     SR (Z)  - 0 if node could be moved, else 1.
  2194.  
  2195.    BUGS
  2196.     none known
  2197.  
  2198.    SEE ALSO
  2199.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  2200.     GU_FindNode(), GU_NodeUp(), GU_CountNodes(), GU_NewList(), GU_SortList()
  2201. gadutil.library/GU_NodeUp                           gadutil.library/GU_NodeUp
  2202.  
  2203.    NAME
  2204.     GU_NodeUp -- Move a node one step towards the top of the list
  2205.  
  2206.    SYNOPSIS
  2207.     success = GU_NodeUp(node, list)
  2208.     D0,SR(Z)            A0    A1
  2209.  
  2210.     BOOL GU_NodeUp(struct Node *, struct List *);
  2211.  
  2212.    FUNCTION
  2213.     Move a node one step up. You can also use the function GU_NodeDown()
  2214.     for moving downwards.
  2215.  
  2216.    INPUTS
  2217.     node - The node to move.
  2218.     list - The list that the node is a part of.
  2219.  
  2220.    RESULT
  2221.     success - TRUE if the node could be moved, else FALSE
  2222.     SR(Z)   - 0 if the node could be moved, else 1.
  2223.  
  2224.    BUGS
  2225.     none known
  2226.  
  2227.    SEE ALSO
  2228.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList(),
  2229.     GU_FindNode(), GU_NodeDown(), GU_CountNodes(), GU_NewList(), GU_SortList()
  2230. gadutil.library/GU_OpenCatalog                 gadutil.library/GU_OpenCatalog
  2231.  
  2232.    NAME
  2233.     GU_OpenCatalog -- Open a message catalog.
  2234.  
  2235.    SYNOPSIS
  2236.     catalog = GU_OpenCatalog(name, version)
  2237.     D0                       A0    D0
  2238.  
  2239.     struct Catalog *GU_OpenCatalog(STRPTR, ULONG);
  2240.  
  2241.    FUNCTION
  2242.     This function opens a message catalog. Catalogs contain all the
  2243.     text strings that an application uses. These strings can easily
  2244.     be replaced by strings in a different language, which causes the
  2245.     application to magically start operation in that new language.
  2246.  
  2247.     Catalogs originally come from disk files. This function searches
  2248.     for them in the following places:
  2249.  
  2250.         PROGDIR:Catalogs/languageName/name
  2251.         LOCALE:Catalogs/languageName/name
  2252.  
  2253.     where languageName is the name of the language associated with the
  2254.     locale parameter.
  2255.  
  2256.    INPUTS
  2257.     catalogname - the NULL terminated name of the catalog to open (just
  2258.               the name, not the complete path to it).
  2259.  
  2260.     version - required version of the catalog to open. Passign 0 as version
  2261.           number means that the program will accept any found version of
  2262.           the catalog. Other values than 0 means exactly that version.
  2263.  
  2264.    RESULT
  2265.     catalog - A message catalog to use with GU_GetLocaleStr or any of the
  2266.           Locale library functions or NULL. NULL is returned on error
  2267.           or if the application can use its built-in strings instead
  2268.           of loading a catalog from disk.
  2269.  
  2270.    EXAMPLE
  2271.     GU_OpenCatalog("myprogram.catalog",0);
  2272.  
  2273.     will open any version of the catalog file "myprogram.catalog" found
  2274.     in either PROGDIR:Catalogs/languageName/ (where the program was started
  2275.     from), or LOCALE:Catalogs/languageName/.
  2276.  
  2277.     GU_OpenCatalog("myprogram.catalog",5);
  2278.  
  2279.     will open version 5 of the catalog file. If v5 is not available, the
  2280.     program will use its internal strings.
  2281.  
  2282.    NOTES
  2283.     If you want to specify other tags than the version tag, you must
  2284.     use the Locale library OpenCatalog(). This function is generally a
  2285.     shortcut to that function. By using this routine, you may not need
  2286.     to open Locale library at all.
  2287.  
  2288.     This routine assumes that the built-in language of the program is
  2289.     english. If you write your programs in another language, you must
  2290.     open the catalog by yourself.
  2291.  
  2292.    SEE ALSO
  2293.     GU_CloseCatalog(), locale/OpenCatalog()
  2294. gadutil.library/GU_OpenFont                       gadutil.library/GU_OpenFont
  2295.  
  2296.    NAME
  2297.     GU_OpenFont -- Load and get a pointer to a disk or system font.
  2298.  
  2299.    SYNOPSIS
  2300.     font = GU_OpenFont(textAttr)
  2301.     D0                 A0
  2302.  
  2303.     struct TextFont *GU_OpenFont(struct TextAttr *);
  2304.  
  2305.    FUNCTION
  2306.     Open a disk or ROM based font. Uses diskfont library if available.
  2307.     Much easier to use than the standard OpenFont functions.
  2308.  
  2309.    INPUTS
  2310.     textAttr - This is a pointer to a TextAttr structure.
  2311.  
  2312.    RESULT
  2313.     font - Struct TextFont ot NULL for failure.
  2314.  
  2315.    BUGS
  2316.     none known
  2317.  
  2318.    SEE ALSO
  2319.     GU_CloseFont()
  2320. gadutil.library/GU_PostFilterIMsg           gadutil.library/GU_PostFilterIMsg
  2321.  
  2322.    NAME
  2323.     GU_PostFilterIMsg -- Return the unfiltered message after
  2324.                  GU_FilterIMsg() was called, and clean up.
  2325.  
  2326.    SYNOPSIS
  2327.     imsg = GU_PostFilterIMsg(modimsg)
  2328.     D0                       A1
  2329.  
  2330.     struct IntuiMessage *GU_PostFilterIMsg(struct IntuiMessage *);
  2331.  
  2332.    FUNCTION
  2333.     NOTE WELL:  Extremely few programs will actually need this function.
  2334.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  2335.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  2336.  
  2337.     Performs any clean-up necessitated by a previous call to
  2338.     GT_FilterIMsg().  The original IntuiMessage is now yours to handle.
  2339.     Do not interpret the fields of the original IntuiMessage, but
  2340.     rather use only the one you got from GT_FilterIMsg().  You
  2341.     may only do message related things at this point, such as queueing
  2342.     it up or replying it.  Since you got the message with
  2343.     exec.library/GetMsg(), your responsibilities do include replying
  2344.     it with exec.library/ReplyMsg(). This function may be safely
  2345.     called with a NULL parameter.
  2346.  
  2347.    INPUTS
  2348.     modimsg - A modified IntuiMessage obtained with GU_FilterIMsg(),
  2349.               or NULL.
  2350.  
  2351.    RESULT
  2352.     imsg - a pointer to the original IntuiMessage, if GT_FilterIMsg()
  2353.            returned non-NULL.
  2354.  
  2355.    NOTES
  2356.     See gadtools/GT_PostFilterIMsg for more information.
  2357.  
  2358.    SEE ALSO
  2359.     GU_FilterIMsg(), gadtools/GT_PostFilterIMsg()
  2360. gadutil.library/GU_RefreshBoxes               gadutil.library/GU_RefreshBoxes
  2361.  
  2362.    NAME
  2363.     GU_RefreshBoxes -- Redraw all bevel boxes in a window.
  2364.  
  2365.    SYNOPSIS
  2366.     GU_RefreshBoxes(window, gad_info)
  2367.                     A0      A1
  2368.  
  2369.     VOID GU_RefreshBoxes(struct Window *, APTR);
  2370.  
  2371.    FUNCTION
  2372.     Redraw all bevel boxes and PROGRESS_KIND gadgets in a window.
  2373.     Also refreshes all text in the window that is created by the
  2374.     LABEL_KIND gadget. This function is basically the same as
  2375.     GU_RefreshWindow, without a call to the GT_RefreshWindow
  2376.     function.
  2377.  
  2378.    INPUTS
  2379.     window - Window to be refreshed.
  2380.  
  2381.     gad_info - The value returned by GU_LayoutGadgetsA()
  2382.  
  2383.    RESULT
  2384.     none
  2385.  
  2386.    BUGS
  2387.     no known
  2388.  
  2389.    SEE ALSO
  2390.     GU_UpdateProgress(), GU_RefreshWindow()
  2391. gadutil.library/GU_RefreshWindow             gadutil.library/GU_RefreshWindow
  2392.  
  2393.    NAME
  2394.     GU_RefreshWindow -- Redraw bevel boxes and gadgets in a window.
  2395.  
  2396.    SYNOPSIS
  2397.     GU_RefreshWindow(window, gad_info)
  2398.                      A0      A1
  2399.  
  2400.     VOID GU_RefreshWindow(struct Window *, APTR);
  2401.  
  2402.    FUNCTION
  2403.     Perform the initial refresh of all the GadTools gadgets you have
  2404.     created. After you have opened your window, you must call this
  2405.     function. Or, if you have opened your window without gadgets,
  2406.     you add the gadgets with intuition/AddGList(), refresh them using
  2407.     intuition/RefreshGList(), then call this function. You should not
  2408.     need this function at other times.
  2409.  
  2410.     This function differs from the gadtools/GT_RefreshWindow(), in that
  2411.     is also renders all bevelbox kind gadgets. If NULL is given in
  2412.     gad_info, no boxes will be rendered, and this function will work
  2413.     exactly as the GT_RefreshWindow().
  2414.  
  2415.    INPUTS
  2416.     window - pointer to the window containing GadTools gadgets.
  2417.  
  2418.     gad_info - the value returned from GU_LayoutGadgetsA(), or NULL.
  2419.  
  2420.    SEE ALSO
  2421.     GU_RefreshBoxes(), GU_UpdateProgress()
  2422. gadutil.library/GU_ReplyIMsg                     gadutil.library/GU_ReplyIMsg
  2423.  
  2424.    NAME
  2425.     GU_ReplyIMsg -- Reply a message obtained with GU_GetIMsg().
  2426.  
  2427.    SYNOPSIS
  2428.     GU_ReplyIMsg(imsg)
  2429.                  A1
  2430.  
  2431.     VOID GU_ReplyIMsg(struct IntuiMessage *);
  2432.  
  2433.    FUNCTION
  2434.     Return a modified IntuiMessage obtained with GU_GetIMsg(). If you
  2435.     use GU_GetIMsg(), use this function where you would normally have
  2436.     used exec/ReplyIMsg() or gadtools/GT_ReplyIMsg(). You may safely
  2437.     call this function with a NULL pointer (nothing will be done).
  2438.  
  2439.    INPUTS
  2440.     imsg - a modified IntuiMessage obtained with GT_GetIMsg(), or NULL
  2441.            in which case this function does nothing.
  2442.  
  2443.    NOTES
  2444.     When using GadUtil, you MUST explicitly GU_ReplyIMsg() all messages
  2445.     you receive. You cannot depend on CloseWindow() to handle messages
  2446.     you have not replied.
  2447.  
  2448.     Starting with V39, this function actually expects a pointer to an
  2449.     ExtIntuiMessage structure, but the prototype was not changed for
  2450.     source code compatibility with older software.
  2451.  
  2452.    SEE ALSO
  2453.     GU_GetIMsg()
  2454. gadutil.library/GU_SetGadgetAttrsA         gadutil.library/GU_SetGadgetAttrsA
  2455.  
  2456.    NAME
  2457.     GU_SetGadgetAttrsA -- Change the attributes of a GadTools gadget.
  2458.  
  2459.    SYNOPSIS
  2460.     GU_SetGadgetAttrsA(gad, win, req, taglist)
  2461.                        A0    A1  A2   A3
  2462.  
  2463.     VOID GU_SetGadgetAttrsA(struct Gadget *, struct Window *,
  2464.                 struct Requester *, struct TagItem *);
  2465.  
  2466.    FUNCTION
  2467.     Change the attributes of the specified gadget, according to the
  2468.     attributes chosen in the tag list. If an attribute is not provided
  2469.     in the tag list, its value remains the unchanged. This function
  2470.     also stores some information for the hotkey part of the library.
  2471.  
  2472.     Use this in place of the gadtools function GT_SetGadgetAttrsA().
  2473.  
  2474.    INPUTS
  2475.     gad - pointer to the gadget in question. This address may be NULL,
  2476.           in which case this function does nothing.
  2477.  
  2478.     win - pointer to the window containing the gadget. Starting with
  2479.           V39 (of the OS), this value may be NULL, in which case the
  2480.           internal attributes of the gadgets are altered but no
  2481.           rendering occurs.
  2482.  
  2483.     req - reserved for future use, should always be NULL.
  2484.  
  2485.     taglist - pointer to an array of tags providing optional extra
  2486.           parameters, or NULL.
  2487.  
  2488.    TAGS
  2489.     See the GadTools function GT_SetGadgetAttrsA() for all tags, since
  2490.     this is an extended version of that routine.
  2491.  
  2492.    NOTES
  2493.     This function may not be called inside of a GU_BeginRefesh() /
  2494.     GU_EndRefresh() session. (as always, restrict yourself to simple
  2495.     rendering functions).
  2496.  
  2497.    SEE ALSO
  2498.     gadtools/GT_SetGadgetAttrsA(), GU_GetGadgetAttrsA()
  2499. gadutil.library/GU_SetGUGadAttrsA           gadutil.library/GU_SetGUGadAttrsA
  2500.  
  2501.    NAME
  2502.     GU_SetGUGadAttrsA -- Change the attributes of a GadUtil gadget.
  2503.  
  2504.    SYNOPSIS
  2505.     GU_SetGUGadAttrsA(gad_info, gad, win, taglist)
  2506.                           A0        A1   A2   A3
  2507.  
  2508.     VOID GU_SetGadAttrsA(APTR, struct Gadget *, struct Window *,
  2509.                 struct TagItem *);
  2510.  
  2511.    FUNCTION
  2512.     Change attributes of a GadUtil gadget.
  2513.  
  2514.    INPUTS
  2515.     gad_info - The value returned by LayoutGadgetsA().
  2516.     gad      - Pointer to the gadget in question.
  2517.     win      - Pointer to the window containing the gadget.
  2518.     taglist  - Pointer to a TagItem list.
  2519.    TAGS
  2520.     See GU_LayoutGadgetsA() for tags.
  2521.  
  2522.    RESULT
  2523.     none
  2524.  
  2525.    SEE ALSO
  2526. gadutil.library/GU_SetToggle                     gadutil.library/GU_SetToggle
  2527.  
  2528.    NAME
  2529.     GU_SetToggle -- Change status of a toggle-select gadget.
  2530.  
  2531.    SYNOPSIS
  2532.     GU_SetToggle(status, gadget, window)
  2533.                  D0,     A0,     A1
  2534.  
  2535.     VOID GU_SetToggle(BOOL, struct Gadget *, struct Window *);
  2536.  
  2537.    FUNCTION
  2538.     This function selects or unselects a toggle gadget, that means a
  2539.     gadget with the tag GU_ToggleSelect set to TRUE.
  2540.  
  2541.     For some more information about the tags, look in <libraries/gadutil.h>
  2542.     or in the autodoc for the GU_LayoutGadgetsA() function.
  2543.  
  2544.    INPUTS
  2545.     status - New status for the gadget. TRUE for selected, FALSE for
  2546.              unselected.
  2547.     gadget - The gadget to change.
  2548.     window - Window that the gadget is located in.
  2549.  
  2550.    RESULT
  2551.     none
  2552.  
  2553.    BUGS
  2554.     none known
  2555.  
  2556.    SEE ALSO
  2557.     GU_LayoutGadgetsA(), <libraries/gatutil.h>, <libraries/gadutil.i>
  2558. gadutil.library/GU_SizeWindow                   gadutil.library/GU_SizeWindow
  2559.  
  2560.    NAME
  2561.     GU_SizeWindow -- Resize a window, and moves it if necessary
  2562.  
  2563.    SYNOPSIS
  2564.     success = GU_SizeWindow(window, deltax, deltay)
  2565.     D0,SR(Z)                A0      D0      D1
  2566.  
  2567.     BOOL GU_SizeWindow(struct Window *, WORD, WORD);
  2568.  
  2569.    FUNCTION
  2570.     This function sends a reuqest to Intuition asking to size the window
  2571.     the specified amounts. The delta arguments describes how much to
  2572.     size the window along the respective axes.
  2573.  
  2574.     This function works like the Intuition function SizeWindow(), and the
  2575.     parameters are also the same. This function also moves the window
  2576.     automatically if it could not be sized at the current position.
  2577.  
  2578.     Remember that this function does not change the window immediately.
  2579.     Just like the Intuition functions SizeWindow(), MoveWindow() and
  2580.     ChangeWindowBox(), you have to wait for a IDCMP_CHANGEWINDOW IDCMP
  2581.     message to arrive.
  2582.  
  2583.     An extra feature of GU_SizeWindow is that it sends back a result,
  2584.     telling you if the window could be resized or not.
  2585.  
  2586.    INPUTS
  2587.     window - pointer to the structure of the window to be sized
  2588.  
  2589.     deltax - signed value describing how much to size the window
  2590.              on the x-axis
  2591.  
  2592.     deltay - signed value describing how much to size the window
  2593.              on the y-axis
  2594.  
  2595.    RESULT
  2596.     success - TRUE if the window could be sized the specified amount
  2597.  
  2598.     SR(Z)   - 0 if function returns TRUE, 1 otherwise
  2599.  
  2600.    BUGS
  2601.     none known
  2602.  
  2603.    SEE ALSO
  2604.     intuition/ChangeWindowBox(), intuition/SizeWindow()
  2605.     intuition/MoveWindow()
  2606. gadutil.library/GU_SortList                       gadutil.library/GU_SortList
  2607.  
  2608.    NAME
  2609.     GU_SortList -- Sorts all nodes in a list.
  2610.  
  2611.    SYNOPSIS
  2612.     GU_SortList(list,slavelist)
  2613.                 A0   A1
  2614.  
  2615.     VOID GU_SortList(struct List *, struct List *);
  2616.  
  2617.    FUNCTION
  2618.     Sorts all items an a list and optionally in a slave list.
  2619.  
  2620.     The slave list option can be used eg. if you have a ListView
  2621.     gadget that shows a number of filenames and another list
  2622.     with the path-names to the files in the other list.
  2623.  
  2624.     Note that the slavelist pointer must be NULL if not used.
  2625.  
  2626.    INPUTS
  2627.     list      - A pointer to the list to sort
  2628.     slavelist - A pointer to an optional slave list (or NULL).
  2629.  
  2630.    NOTES
  2631.     Written in assembler using Shell-sort, so it is quite fast..
  2632.  
  2633.    SEE ALSO
  2634.     GU_AddTail(), GU_ClearList(), GU_DetachList(), GU_AttachList()
  2635.     GU_FindNode(), GU_NodeUp(), GU_NodeDown(), GU_NewList(), GU_CountNodes()
  2636. gadutil.library/GU_TextWidth                     gadutil.library/GU_TextWidth
  2637.  
  2638.    NAME
  2639.     GU_TextWidth -- Calculate the pixel length of a text string.
  2640.  
  2641.    SYNOPSIS
  2642.     textwidth = GU_TextWidth(string, textattr)
  2643.     D0                       A0      A1
  2644.  
  2645.     ULONG GU_TextWidth(STRPTR, struct TextAttr *);
  2646.  
  2647.    FUNCTION
  2648.     Calculate the length of the text, using the specified font. This
  2649.     function will open the required font, if it isn't opened before.
  2650.  
  2651.    INPUTS
  2652.     string - NULL terminated text to calculate width of.
  2653.  
  2654.     textattr - a filled in TextAttr structure.
  2655.  
  2656.    RESULT
  2657.     textwidth - pixel length of the text
  2658. gadutil.library/GU_UpdateProgress           gadutil.library/GU_UpdateProgress
  2659.  
  2660.    NAME
  2661.     GU_UpdateProgress -- Redraw all or specified progress gadget(s).
  2662.  
  2663.    SYNOPSIS
  2664.     GU_UpdateProgress(window, gad_info, gadget)
  2665.                       A0      A1        A2
  2666.  
  2667.     VOID GU_UpdateProgress(struct Window *, APTR, struct ProgressGad *);
  2668.  
  2669.    FUNCTION
  2670.         Redraws all or one specified PROGRESS_KIND gadget in a window.
  2671.  
  2672.    INPUTS
  2673.         window - the window that the progress gadget is in.
  2674.  
  2675.         gad_info - the value returned from GU_LayoutGadgetsA()
  2676.  
  2677.         gadget - NULL, or a pointer to a specified progress gadget to
  2678.                  redraw. If NULL is given, all progress gadgets will be
  2679.                  redrawn. Use this function to redraw the progress gad
  2680.                  after changing the total or current value.
  2681.                  This function is called automatically from GU_Refresh-
  2682.                  Boxes.
  2683.  
  2684.    SEE ALSO
  2685.         GU_RefreshBoxes(), GU_RefreshWindow()
  2686.